z18n – zgo.at/z18n Index | Files | Directories

package z18n

import "zgo.at/z18n"

Package z18n provides translations ("internationalisation", or "i18n").

A detailed guide to get started is available in the project README at: https://github.com/arp242/z18n



func T

func T(ctx context.Context, id string, data ...interface{}) string

T translates a string, like Locale.T. the Locale is fetched from the context.

func Tag

func Tag(tagName, content string, innerHTML ...string) tag

Tag creates a new tag.

func Thtml

func Thtml(ctx context.Context, id string, data ...interface{}) template.HTML

Thtml is like T, but returns template.HTML instead of a string.

func With

func With(ctx context.Context, l *Locale) context.Context

With returns a copy of the context with the Locale as a value.


type Bundle

type Bundle struct {
	// NoHTML disabled automatic HTML escaping.
	// You almost certainly *DON'T* want to set this if you're using a
	// web-app or the like or you may risk XSS security problems.
	// This is provided for cases where you're not using it from a web-app,
	// in which case you probably do want to disable it. It's enabled by
	// default because printing escape codes is ugly but safe, and not
	// escaping in a web app can be disastrous.
	NoHTML bool

	// Mark messages with «msg»; useful mostly when adding z18n to an existing
	// application to visually check for untranslated strings.
	Mark bool

	// Log errors. If an unrecoverable error occurs z18n will add
	// "%(z18n ERROR [msg])" to the string. If this is non-nil then it will
	// also be called with the same string.
	Log func(string)
	// contains filtered or unexported fields

Bundle is a "bundle" of all translations and localisations.

func NewBundle

func NewBundle(defaultLang language.Tag) *Bundle

NewBundle creates a new bundle of languages, falling back to defaultLang if a chosen language doesn't exist.

func (*Bundle) AddMessages

func (b *Bundle) AddMessages(l language.Tag, msg map[string]Msg)

AddMessages adds new messages for this language.

func (*Bundle) Locale

func (b *Bundle) Locale(langs ...string) *Locale

Locale gets the first matching locale for the list of languages.

func (*Bundle) LocaleFromEnv

func (b *Bundle) LocaleFromEnv() *Locale

LocaleFromEnv creates a new Locale from the LANG and LC_* environment variables.

Variables currently used:

LANGUAGES       Colon-separated list of locales
LANG            Default language (one value)
LC_COLLATE      Sorting collation
LC_MESSAGES     Which messages to use
LC_NUMERIC      Number formating
LC_TIME         Date/time formatting
LC_ALL          All of the above.

Lookup order is LC_ALL, LC_*, LANGUAGES (for LC_MESSAGES), and then LANG. The first match wins. So if LC_ALL is set that will just override everything and none of the other values matter. Generally speaking you want to set only LANG, and maybe one of the LC_* variables if you want to override something specific.

TODO: LC_* variables outside of LC_ALL don't do anything; we need to add options to set these values individually.

func (*Bundle) ReadMessages

func (b *Bundle) ReadMessages(fsys fs.FS, path string) error

ReadMessages reads a single messages files.

func (*Bundle) ReadMessagesDir

func (b *Bundle) ReadMessagesDir(fsys fs.FS, glob string) error

ReadMessagesDir reads all message files from fsys matching the glob pattern.

type Locale

type Locale struct {
	// contains filtered or unexported fields

Locale is a single localisation.

func Get

func Get(ctx context.Context) *Locale

Get the Locale value from the context.

func (Locale) Date

func (l Locale) Date(t time.Time, format TimeFormat) string

Date formats the time t in the standard date format for this language.

func (Locale) Datetime

func (l Locale) Datetime(t time.Time, format TimeFormat) string

Datetime formats the time t in the standard datetime format for this language.

func (Locale) FormatTime

func (l Locale) FormatTime(t time.Time, format string) string

FormatTime works like time.Format, except that names such as "Monday" and "March" are translated to this locale.

func (Locale) MonthName

func (l Locale) MonthName(t time.Time, n TimeFormat) string

MonthName gets the name of the month in t.

If timeFormatShort is passed it will return a short name, such as "Apr". Any other value will get the full name: "April".

func (Locale) StartOfWeek

func (l Locale) StartOfWeek() int

StartOfWeek gets the day this weeks starts.

0 is Sunday, 1 is Monday, 6 is Saturday.

func (Locale) T

func (l Locale) T(id string, data ...interface{}) string

T translates a message for this locale.

It will return the message in the bundler's defaultLang if the message is not translated in this language (yet).

The ID can contain any character except a |. Everything after the first | is used as the default message.

Variables can be inserted as %(varname), and text can be wrapped in HTML tags with %[varname translated text]. Wrapping in HTML requires passing a Tagger interface (such as Tag).

Pass N() as any argument to apply pluralisation.

func (Locale) Time

func (l Locale) Time(t time.Time, format TimeFormat) string

Time formats the time t in the standard time format for this language.

func (Locale) TwentyFourHours

func (l Locale) TwentyFourHours() bool

TwentyFourHours reports if this region uses a 24-hour clock.

func (Locale) WeekdayName

func (l Locale) WeekdayName(t time.Time, n TimeFormat) string

WeekdayName gets the name of the weekday in t.

If timeFormatShort is passed it will return a short name, such as "Wed". Any other value will get the full name: "Wednesday".

type Msg

type Msg struct {
	ID      string  // Message ID.
	Plural  *Plural // Plural value; may be nil.
	Default string  // CLDR "other" plural (default is more intuitive IMO).
	Zero    string  // CLDR "zero" plural.
	One     string  // CLDR "one" plural.
	Two     string  // CLDR "two" plural.
	Few     string  // CLDR "few" plural.
	Many    string  // CLDR "many" plural.
	// contains filtered or unexported fields

Msg is a localized message.

func (Msg) Display

func (m Msg) Display(l *Locale) string

String displays this string as "other", or the ID if this isn't set.

type P

type P map[string]interface{}

P is a shortcut for T() map parameters.

type Plural

type Plural int

Plural signals to T that this parameter is used to pluralize the string, rather than a data parameter.

func N

func N(n int) Plural

N returns a plural of n.

func (Plural) String

func (p Plural) String() string

type Tagger

type Tagger interface {
	Open() string
	Close() string
	Text() string

type TimeFormat

type TimeFormat uint8

TimeFormat controls which standard time format to print

const (
	TimeFormatFull TimeFormat = iota

Standard date, time, and datetime lengths.

See localize.Date(), localize.Time(), and localize.Datetime() for some examples.

For time and datetime the CLDR specifies that a full time zone name should be printed for most regions, such as "Western Argentina Time" or "Bhutan Time". Do you know what actual TZ those are? Probably not. So this replaces that with "MST -0700" instead (abbrevated timezone name + offset), which is far more useful in almost all cases (and also avoids having to include a large list of timezone names for every language).

Source Files

gen_data.go locale.go messages.go msg.go simplify.go z18n.go


msgfilePackage msgfile manages message files.
pluralPackage plural provides support for pluralizing messages according to CLDR rules http://cldr.unicode.org/index/cldr-spec/plural-rules
v0.0.0-20240522230155-4d5af439f8c4 (latest)
May 22, 2024
17 packages
Last checked
1 week ago

Tools for package owners.