i18n

Documentation

Overview

Package i18n is responsible for keeping the key internationalization in one place.

Index

• Constants
• func ExpandKey(ctx context.Context, key string) string
• func N(ctx context.Context, key string, n int, args ...any) string
• func T(ctx context.Context, key string, args ...any) string
• func WithScope(ctx context.Context, key string) context.Context
• type Code
  • func ParseAcceptLanguage(txt string) []Code
  • func (c Code) Base() Code
  • func (c Code) String() string
• type DefaultText
  • func Default(txt string) DefaultText
• type Dict
  • func NewDict() *Dict
  • func (d *Dict) Add(key string, value any)
  • func (d *Dict) Get(key string) *Dict
  • func (d *Dict) Merge(d2 *Dict)
  • func (d *Dict) UnmarshalJSON(data []byte) error
  • func (d *Dict) Value() string
• type Locale
  • func GetLocale(ctx context.Context) *Locale
  • func NewLocale(code Code, dict *Dict) *Locale
  • func (l *Locale) Code() Code
  • func (l *Locale) N(key string, n int, args ...any) string
  • func (l *Locale) PluralRule() PluralRule
  • func (l *Locale) T(key string, args ...any) string
  • func (l *Locale) UnmarshalJSON(data []byte) error
  • func (l *Locale) WithContext(ctx context.Context) context.Context
• type Locales
  • func (ls *Locales) Codes() []Code
  • func (ls *Locales) Get(code Code) *Locale
  • func (ls *Locales) Load(src fs.FS) error
  • func (ls *Locales) LoadWithDefault(src fs.FS, locale Code) error
  • func (ls *Locales) Match(locale string) *Locale
  • func (ls *Locales) UnmarshalJSON(data []byte) error
• type M
  • func (m M) Replace(in string) string
• type PluralRule
  • func GetRule(key string) PluralRule

Constants

const (
	DefaultRuleKey = "default"
)

Standard pluralization rule keys.

Functions

func ExpandKey

func ExpandKey(ctx context.Context, key string) string

ExpandKey extracts the current scope from the context and appends it to the start of the provided key.

func N

func N(ctx context.Context, key string, n int, args ...any) string

N returns the pluralized translation of the provided key using n as the count.

func T

func T(ctx context.Context, key string, args ...any) string

T is responsible for translating a key into a string by extracting the local from the context.

func WithScope

func WithScope(ctx context.Context, key string) context.Context

WithScope is used to add a new scope to the context. To use this, use a `.` at the beginning of keys.

Types

type Code

type Code string

Code is used to represent a language code which follows the ISO 639-1 standard, with sub-tags aggregated with hyphens, as defined in [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646). Examples include:

fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN

func ParseAcceptLanguage

func ParseAcceptLanguage(txt string) []Code

ParseAcceptLanguage provides an ordered set of codes extracted from an HTTP "Accept-Language" header as defined in RFC9110. Current implementation will ignore quality values and instead just assume the order of the provided codes is valid.

func (Code) Base

func (c Code) Base() Code

Base returns the base language code, without any subtags.

func (Code) String

func (c Code) String() string

String returns the string variant of the code.

type DefaultText

type DefaultText string

DefaultText when detected as an argument to a translation function will be used if no language match is found.

func Default

func Default(txt string) DefaultText

Default when used as an argument to a translation function ensure the provided txt is used as a default value if no language match is found.

type Dict

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

Dict holds the internationalization entries for a specific locale.

func NewDict

func NewDict() *Dict

NewDict instantiates a new dict object.

func (*Dict) Add

func (d *Dict) Add(key string, value any)

Add adds a new key value pair to the dictionary.

func (*Dict) Get

func (d *Dict) Get(key string) *Dict

Get recursively retrieves the dictionary at the provided key location.

func (*Dict) Merge

func (d *Dict) Merge(d2 *Dict)

Merge combines the entries of the second dictionary into this one. If a key is duplicated in the second diction, the original value takes priority.

func (*Dict) UnmarshalJSON

func (d *Dict) UnmarshalJSON(data []byte) error

UnmarshalJSON attempts to load the dictionary data from a JSON byte slice.

func (*Dict) Value

func (d *Dict) Value() string

Value returns the dictionary value or an empty string if the dictionary is nil.

type Locale

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

Locale holds the internationalization entries for a specific locale.

func GetLocale

func GetLocale(ctx context.Context) *Locale

GetLocale retrieves the locale from the context.

func NewLocale

func NewLocale(code Code, dict *Dict) *Locale

NewLocale creates a new locale with the provided key and dictionary.

func (*Locale) Code

func (l *Locale) Code() Code

Code returns the language code of the locale.

func (*Locale) N

func (l *Locale) N(key string, n int, args ...any) string

N uses the locale pluralization rules to determine which string value to provide based on the provided number.

func (*Locale) PluralRule

func (l *Locale) PluralRule() PluralRule

PluralRule provides the pluralization rule for the locale.

func (*Locale) T

func (l *Locale) T(key string, args ...any) string

T provides the value from the dictionary stored by the locale.

func (*Locale) UnmarshalJSON

func (l *Locale) UnmarshalJSON(data []byte) error

UnmarshalJSON attempts to load the locale from a JSON byte slice.

func (*Locale) WithContext

func (l *Locale) WithContext(ctx context.Context) context.Context

WithContext inserts the locale into the context so that it can be loaded later with `GetLocale`.

type Locales

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

Locales is a map of language keys to their respective locale.

func (*Locales) Codes

func (ls *Locales) Codes() []Code

Codes provides a list of locale codes defined in the list.

func (*Locales) Get

func (ls *Locales) Get(code Code) *Locale

Get provides the define Locale object for the matching key.

func (*Locales) Load

func (ls *Locales) Load(src fs.FS) error

Load walks through all the files in the provided File System and merges every one with the current list of locales.

func (*Locales) LoadWithDefault

func (ls *Locales) LoadWithDefault(src fs.FS, locale Code) error

LoadWithDefault performs the regular load operation, but follows up with a second operation that will ensure that default dictionary is merged with every other locale, thus ensuring that every text will have a fallback.

func (*Locales) Match

func (ls *Locales) Match(locale string) *Locale

Match attempts to find the best possible matching locale based on the locale string provided. The locale string is parsed according to the "Accept-Language" header format defined in RFC9110.

func (*Locales) UnmarshalJSON

func (ls *Locales) UnmarshalJSON(data []byte) error

UnmarshalJSON attempts to load the locales from a JSON byte slice and merge them into any existing locales.

type M

type M map[string]any

M stands for map and is a simple helper to make it easier to work with internationalization maps.

func (M) Replace

func (m M) Replace(in string) string

Replace is used to interpolate the matched keys in the provided string with their values in the map.

Interpolation is performed using the `%{key}` pattern.

type PluralRule

type PluralRule func(d *Dict, num int) *Dict

PluralRule defines a simple method that expects a dictionary and number and will find a matching dictionary entry.

func GetRule

func GetRule(key string) PluralRule

GetRule provides the PluralRule for the given key.