i18n

Documentation

Overview

Package i18n provides internalization and localization features for Iris. To use with net/http see https://github.com/kataras/i18n instead.

Index

• Variables
• type I18n
  • func New() *I18n
  • func (i *I18n) GetLocale(ctx *context.Context) context.Locale
  • func (i *I18n) Load(globPattern string, languages ...string) error
  • func (i *I18n) LoadAssets(assetNames func() []string, asset func(string) ([]byte, error), ...) error
  • func (i *I18n) LoadFS(fileSystem fs.FS, pattern string, languages ...string) error
  • func (i *I18n) Loaded() bool
  • func (i *I18n) Reset(loader Loader, languages ...string) error
  • func (i *I18n) SetDefault(langCode string) bool
  • func (i *I18n) Tags() []language.Tag
  • func (i *I18n) Tr(lang, key string, args ...interface{}) string
  • func (i *I18n) TrContext(ctx *context.Context, key string, args ...interface{}) string
  • func (i *I18n) TryMatchString(s string) (language.Tag, int, bool)
  • func (i *I18n) Wrapper() router.WrapperFunc
• type Loader
  • func Assets(assetNames func() []string, asset func(string) ([]byte, error), ...) Loader
  • func FS(fileSystem fs.FS, pattern string, options LoaderConfig) (Loader, error)
  • func Glob(globPattern string, options LoaderConfig) Loader
• type LoaderConfig
• type Localizer
• type Matcher
  • func (m *Matcher) Match(t ...language.Tag) (language.Tag, int, language.Confidence)
  • func (m *Matcher) MatchOrAdd(t language.Tag) (tag language.Tag, index int, conf language.Confidence)
  • func (m *Matcher) ParseLanguageFiles(fileNames []string) (map[int][]string, error)
• type MessageFunc

Variables

var DefaultLoaderConfig = LoaderConfig{
	Left:               "{{",
	Right:              "}}",
	Strict:             false,
	DefaultMessageFunc: nil,
	PluralFormDecoder:  internal.DefaultPluralFormDecoder,
	Funcs:              nil,
}

DefaultLoaderConfig represents the default loader configuration.

Types

type I18n

type I18n struct {
	Loader LoaderConfig

	// ExtractFunc is the type signature for declaring custom logic
	// to extract the language tag name.
	// Defaults to nil.
	ExtractFunc func(ctx *context.Context) string
	// DefaultMessageFunc is the field which can be used
	// to modify the behavior when a key or language was not found.
	// All language inputs fallback to the default locale if not matched.
	// This is why this one accepts both input and matched languages,
	// so the caller can be more expressful knowing those.
	//
	// Defaults to nil.
	DefaultMessageFunc MessageFunc

	// If not empty, it is language identifier by url query.
	//
	// Defaults to "lang".
	URLParameter string
	// If not empty, it is language identifier by cookie of this name.
	//
	// Defaults to empty.
	Cookie string
	// If true then a subdomain can be a language identifier.
	//
	// Defaults to true.
	Subdomain bool
	// If a DefaultMessageFunc is NOT set:
	// If true then it will return empty string when translation for a
	// specific language's key was not found.
	// Defaults to false, fallback defaultLang:key will be used.
	// Otherwise, DefaultMessageFunc is called in either case.
	Strict bool

	// If true then Iris will wrap its router with the i18n router wrapper on its Build state.
	// It will (local) redirect requests like:
	// 1. /$lang_prefix/$path to /$path with the language set to $lang_prefix part.
	// 2. $lang_subdomain.$domain/$path to $domain/$path with the language set to $lang_subdomain part.
	//
	// Defaults to true.
	PathRedirect bool
	// contains filtered or unexported fields
}

I18n is the structure which keeps the i18n configuration and implements localization and internationalization features.

func New

func New() *I18n

New returns a new `I18n` instance. Use its `Load` or `LoadAssets` to load languages. Examples at: https://github.com/XpamAmAdEuS/iris/tree/master/_examples/i18n.

func (*I18n) GetLocale

func (i *I18n) GetLocale(ctx *context.Context) context.Locale

GetLocale returns the found locale of a request. It will return the first registered language if nothing else matched.

func (*I18n) Load

func (i *I18n) Load(globPattern string, languages ...string) error

Load is a method shortcut to load files using a filepath.Glob pattern. It returns a non-nil error on failure.

See `New` and `Glob` package-level functions for more.

func (*I18n) LoadAssets

func (i *I18n) LoadAssets(assetNames func() []string, asset func(string) ([]byte, error), languages ...string) error

LoadAssets is a method shortcut to load files using go-bindata. It returns a non-nil error on failure.

See `New` and `Asset` package-level functions for more.

func (*I18n) LoadFS

func (i *I18n) LoadFS(fileSystem fs.FS, pattern string, languages ...string) error

LoadFS is a method shortcut to load files using `embed.FS` or `fs.FS` or `http.FileSystem` or `string` (local directory). The "pattern" is a classic glob pattern.

See `New` and `FS` package-level functions for more. Example: https://github.com/XpamAmAdEuS/iris/blob/master/_examples/i18n/template-embedded/main.go.

func (*I18n) Loaded

func (i *I18n) Loaded() bool

Loaded reports whether `New` or `Load/LoadAssets` called.

func (*I18n) Reset

func (i *I18n) Reset(loader Loader, languages ...string) error

Reset sets the locales loader and languages. It is not meant to be used by users unless a custom `Loader` must be used instead of the default one.

func (*I18n) SetDefault

func (i *I18n) SetDefault(langCode string) bool

SetDefault changes the default language. Please avoid using this method; the default behavior will accept the first language of the registered tags as the default one.

func (*I18n) Tags

func (i *I18n) Tags() []language.Tag

Tags returns the registered languages or dynamically resolved by files. Use `Load` or `LoadAssets` first.

func (*I18n) Tr

func (i *I18n) Tr(lang, key string, args ...interface{}) string

Tr returns a translated message based on the "lang" language code and its key with any optional arguments attached to it.

It returns an empty string if "lang" not matched, unless DefaultMessageFunc. It returns the default language's translation if "key" not matched, unless DefaultMessageFunc.

func (*I18n) TrContext

func (i *I18n) TrContext(ctx *context.Context, key string, args ...interface{}) string

TrContext returns the localized text message for this Context. It returns an empty string if context's locale not matched, unless DefaultMessageFunc. It returns the default language's translation if "key" not matched, unless DefaultMessageFunc.

func (*I18n) TryMatchString

func (i *I18n) TryMatchString(s string) (language.Tag, int, bool)

TryMatchString will try to match the "s" with a registered language tag. It returns -1 as the language index and false if not found.

func (*I18n) Wrapper

func (i *I18n) Wrapper() router.WrapperFunc

Wrapper returns a new router wrapper. The result function can be passed on `Application.WrapRouter/AddRouterWrapper`. It compares the path prefix for translated language and local redirects the requested path with the selected (from the path) language to the router.

You do NOT have to call it manually, just set the `I18n.PathRedirect` field to true.

type Loader

type Loader func(m *Matcher) (Localizer, error)

Loader accepts a `Matcher` and should return a `Localizer`. Functions that implement this type should load locale files.

func Assets

func Assets(assetNames func() []string, asset func(string) ([]byte, error), options LoaderConfig) Loader

Assets accepts a function that returns a list of filenames (physical or virtual), another a function that should return the contents of a specific file and any Loader options. Go-bindata usage. It returns a valid `Loader` which loads and maps the locale files.

See `Glob`, `FS`, `New` and `LoaderConfig` too.

func FS

func FS(fileSystem fs.FS, pattern string, options LoaderConfig) (Loader, error)

LoadFS loads the files using embed.FS or fs.FS or http.FileSystem or string (local directory). The "pattern" is a classic glob pattern.

See `Glob`, `Assets`, `New` and `LoaderConfig` too.

func Glob

func Glob(globPattern string, options LoaderConfig) Loader

Glob accepts a glob pattern (see: https://golang.org/pkg/path/filepath/#Glob) and loads the locale files based on any "options".

The "globPattern" input parameter is a glob pattern which the default loader should search and load for locale files.

See `New` and `LoaderConfig` too.

type LoaderConfig

type LoaderConfig = internal.Options

LoaderConfig the configuration structure which contains some options about how the template loader should act.

See `Glob` and `Assets` package-level functions.

type Localizer

type Localizer interface {
	// GetLocale should return a valid `Locale` based on the language index.
	// It will always match the Loader.Matcher.Languages[index].
	// It may return the default language if nothing else matches based on custom localizer's criteria.
	GetLocale(index int) context.Locale
}

Localizer is the interface which returned from a `Loader`. Types that implement this interface should be able to retrieve a `Locale` based on the language index.

type Matcher

type Matcher struct {
	Languages []language.Tag
	// contains filtered or unexported fields
}

Matcher implements the languae.Matcher. It contains the original language Matcher and keeps an ordered list of the registered languages for further use (see `Loader` implementation).

func (*Matcher) Match

func (m *Matcher) Match(t ...language.Tag) (language.Tag, int, language.Confidence)

Match returns the best match for any of the given tags, along with a unique index associated with the returned tag and a confidence score.

func (*Matcher) MatchOrAdd

func (m *Matcher) MatchOrAdd(t language.Tag) (tag language.Tag, index int, conf language.Confidence)

MatchOrAdd acts like Match but it checks and adds a language tag, if not found, when the `Matcher.strict` field is true (when no tags are provided by the caller) and they should be dynamically added to the list.

func (*Matcher) ParseLanguageFiles

func (m *Matcher) ParseLanguageFiles(fileNames []string) (map[int][]string, error)

ParseLanguageFiles returns a map of language indexes and their associated files based on the "fileNames".

type MessageFunc

type MessageFunc = internal.MessageFunc

MessageFunc is the function type to modify the behavior when a key or language was not found. All language inputs fallback to the default locale if not matched. This is why this signature accepts both input and matched languages, so caller can provide better messages.

The first parameter is set to the client real input of the language, the second one is set to the matched language (default one if input wasn't matched) and the third and forth are the translation format/key and its optional arguments.

Note: we don't accept the Context here because Tr method and template func {{ tr }} have no direct access to it.