i18n

Documentation

Overview

Package i18n provides translation primitives modelled on Laravel's Lang facade.

Messages live in JSON files keyed by locale:

resources/lang/en.json
resources/lang/uz.json
resources/lang/ru.json

Each file is a flat JSON object: `{"welcome": "Hello :name"}`. Nested keys are joined with "." in lookups: `{"auth.failed": "..."}` is referenced as `t.Get("auth.failed", ...)`.

Placeholders use Laravel's `:name` syntax. Pass a map of replacements (or a list of key/value pairs via Replace).

Pluralisation: a key whose value is `{"one": "...", "other": "..."}` is selected based on the count passed via Choice.

Usage:

tr, _ := i18n.Load("resources/lang", "en")
tr.Get("welcome", i18n.M{"name": "Ada"})       // "Hello Ada"
tr.WithLocale("uz").Get("welcome", i18n.M{...}) // "Salom ..."
tr.Choice("apples", 3, i18n.M{"count": "3"})

Index

• Variables
• type M
• type Translator
  • func Load(dir, defaultLocale string) (*Translator, error)
  • func LoadFS(fsys fs.FS, dir, defaultLocale string) (*Translator, error)
  • func (t *Translator) Add(locale string, msgs map[string]any)
  • func (t *Translator) Choice(key string, count int, replace ...M) string
  • func (t *Translator) Current() string
  • func (t *Translator) Default() string
  • func (t *Translator) Get(key string, replace ...M) string
  • func (t *Translator) Has(key string) bool
  • func (t *Translator) SetFallback(locale string) *Translator
  • func (t *Translator) WithLocale(locale string) *Translator

Variables

var ErrLocaleMissing = errors.New("i18n: locale not loaded")

ErrLocaleMissing is returned when no messages are loaded for the requested locale.

Types

type M

type M map[string]string

M is a shorthand for a map of placeholder replacements.

type Translator

type Translator struct {
	// contains filtered or unexported fields
}

Translator holds the loaded messages for one or more locales.

func Load

func Load(dir, defaultLocale string) (*Translator, error)

Load reads every *.json file in dir, treating the basename as the locale code. The default locale is set to `defaultLocale`.

func LoadFS

func LoadFS(fsys fs.FS, dir, defaultLocale string) (*Translator, error)

LoadFS is the io/fs.FS-backed variant for embedded files.

func (*Translator) Add

func (t *Translator) Add(locale string, msgs map[string]any)

Add registers a locale from a flat key/value map. Useful for tests.

func (*Translator) Choice

func (t *Translator) Choice(key string, count int, replace ...M) string

Choice returns the pluralised form for key based on count. The underlying value must be a map with at least "other"; "one" is used when count==1, "zero" when count==0 (if defined).

The literal value of count is also exposed as :count in the substitution map so messages like `":count items"` work without extra boilerplate.

func (*Translator) Current

func (t *Translator) Current() string

Current returns the active locale.

func (*Translator) Default

func (t *Translator) Default() string

Default returns the original default locale (set at Load time).

func (*Translator) Get

func (t *Translator) Get(key string, replace ...M) string

Get returns the translated message for key, substituting :placeholder occurrences from replace. If the key is missing from the active locale, the fallback locale is consulted. If still missing, the key itself is returned (helps spot missing translations in development).

func (*Translator) Has

func (t *Translator) Has(key string) bool

Has reports whether the active locale defines key.

func (*Translator) SetFallback

func (t *Translator) SetFallback(locale string) *Translator

SetFallback designates the locale used when a key is missing from the active locale.

func (*Translator) WithLocale

func (t *Translator) WithLocale(locale string) *Translator

WithLocale returns a shallow clone with the requested active locale. The underlying messages map is shared (read-only).