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

Index ¶

• func T(ctx context.Context, id string, data ...interface{}) string
• func Tag(tagName, content string, innerHTML ...string) tag
• func Thtml(ctx context.Context, id string, data ...interface{}) template.HTML
• func With(ctx context.Context, l *Locale) context.Context
• type Bundle
• func NewBundle(defaultLang language.Tag) *Bundle
• func (b *Bundle) AddMessages(l language.Tag, msg map[string]Msg)
• func (b *Bundle) Locale(langs ...string) *Locale
• func (b *Bundle) LocaleFromEnv() *Locale
• func (b *Bundle) ReadMessages(fsys fs.FS, path string) error
• func (b *Bundle) ReadMessagesDir(fsys fs.FS, glob string) error
• type Locale
• func Get(ctx context.Context) *Locale
• func (l Locale) Date(t time.Time, format TimeFormat) string
• func (l Locale) Datetime(t time.Time, format TimeFormat) string
• func (l Locale) FormatTime(t time.Time, format string) string
• func (l Locale) MonthName(t time.Time, n TimeFormat) string
• func (l Locale) StartOfWeek() int
• func (l Locale) T(id string, data ...interface{}) string
• func (l Locale) Time(t time.Time, format TimeFormat) string
• func (l Locale) TwentyFourHours() bool
• func (l Locale) WeekdayName(t time.Time, n TimeFormat) string
• type Msg
• func (m Msg) Display(l *Locale) string
• type P
• type Plural
• func N(n int) Plural
• func (p Plural) String() string
• type Tagger
• type TimeFormat

Functions ¶

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.

Types ¶

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
	TimeFormatLong
	TimeFormatMedium
	TimeFormatShort
)

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

Directories ¶