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

• type I18n
  • func New() *I18n
  • func (i *I18n) GetLocale(ctx context.Context) context.Locale
  • func (i *I18n) GetMessage(ctx context.Context, format string, args ...interface{}) string
  • 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) 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, format 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 Glob(globPattern string, options ...LoaderOption) Loader
• type LoaderConfig
• type LoaderOption
• 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 MemoryLocalizer
  • func (l MemoryLocalizer) GetLocale(index int) context.Locale
  • func (l MemoryLocalizer) SetDefault(index int) bool

Types

type I18n

type I18n struct {

	// ExtractFunc is the type signature for declaring custom logic
	// to extract the language tag name.
	// Defaults to nil.
	ExtractFunc func(ctx context.Context) string
	// 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 true then it will return empty string when translation for a a specific language's key was not found.
	// Defaults to false, fallback defaultLang:key will be used.
	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.

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) GetMessage

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

GetMessage returns the localized text message for this "r" request based on the key "format".

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) 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, format string, args ...interface{}) string

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

It returns an empty string if "format" not matched.

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`. 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 ...LoaderOption) 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`, `Assets`, `New` and `LoaderConfig` too.

func Glob

func Glob(globPattern string, options ...LoaderOption) 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 struct {
	// Template delimeters, defaults to {{ }}.
	Left, Right string
	// Template functions map, defaults to nil.
	FuncMap template.FuncMap
	// If true then it will return error on invalid templates instead of moving them to simple string-line keys.
	// Also it will report whether the registered languages matched the loaded ones.
	// Defaults to false.
	Strict bool
}

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

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

type LoaderOption

type LoaderOption func(*LoaderConfig)

LoaderOption is a type which accepts a pointer to `LoaderConfig` and can be optionally passed to the second variadic input argument of the `Glob` and `Assets` 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 MemoryLocalizer

type MemoryLocalizer map[int]context.Locale

MemoryLocalizer is a map which implements the `Localizer`.

func (MemoryLocalizer) GetLocale

func (l MemoryLocalizer) GetLocale(index int) context.Locale

GetLocale returns a valid `Locale` based on the "index".

func (MemoryLocalizer) SetDefault

func (l MemoryLocalizer) SetDefault(index int) bool

SetDefault changes the default language based on the "index". See `I18n#SetDefault` method for more.