Documentation ¶
Overview ¶
Package i18n4v provides i18n feature including pluralisation support, replacing kes, contextual translation to Golang. It is a member of https://i18n4v.js.org family. JavaScript runtime and this packages uses same translation format (JSON).
It supports translation via default translator instance or independent translator instances.
Default translator is good for command line tools. To use default translator, you can initialize via Add() function (and AddFromString(), MustAdd(), MustAddFromString()), and translate via global Translate() function.
Independent translator is good for web services, each client have their own preferred languages (in Accept-Language header). To use independent translator, you can create via Craete() function (and CreateFromString(), MustCreate(), MustCreateFromStrgin()), and translate via Translate() method of the instance.
The simplest translation is selecting words from language JSON:
i18n4v.MustAddFromString(`{ "values": { "Cancel": "Cancelar" } }`) _ := i18n4v.Translate _("Cancel") // -> Cancelar
The following JSON provides pluralisation support. Each array contains matching pattern(minimum value and maximum value) and translation. null means math.MinInt64 or math.MaxInt64. %n and -%n are replaced with the number in parameter:
i18n4v.MustAddFromString(`{ "values": { "%n comments": [ [0, 0, "%n comments"], [1, 1, "%n comment"], [2, null, "%n comments"] ] } }`) _ := i18n4v.Translate _("%n comments", 1) // -> 1 comment
%{key} is replaced via replacement parameters. Parameter should be passed via Replace container (this is an alias of map[string]string):
_ := i18n4v.Translate _("Welcome %{name}", i18n4v.Replace{"name":"John"}) // -> Welcome John
If translation is missing, it passes through translation keys as a translations. You can pass text for fall back:
_ := i18n4v.Translate _("_short_key", "This is a long piece of text") // -> This is a long piece of text
Context feature supports selecting translations from context (like gender). Of cource, you can use all features together that are described before:
MustAddFromString(`{ "contexts": [ { "matches": {"gender": "male"}, "values": { "%{name} uploaded %n photos to their %{album} album": [ [0, 0, "%{name} uploaded %n photos to his %{album} album"], [1, 1, "%{name} uploaded %n photo to his %{album} album"], [2, null, "%{name} uploaded %n photos to his %{album} album"] ] } }, { "matches": {"gender":"female"}, "values": { "%{name} uploaded %n photos to their %{album} album": [ [0, 0, "%{name} uploaded %n photos to her %{album} album"], [1, 1, "%{name} uploaded %n photo to her %{album} album"], [2, null, "%{name} uploaded %n photos to her %{album} album"] ] } } ] }`) _ := i18n4v.Translate _("%{name} uploaded %n photos to their %{album} album", 4, Replace{"name": "Jane", "album": "Hen's Night" }, Context{"gender": "female" }) // -> Jane uploaded 4 photos to her Hen's Night album
This package is released under MIT license.
Index ¶
- func Add(reader io.Reader, tag ...language.Tag) error
- func AddFromString(json string, tag ...language.Tag) error
- func AddWord(key, value string, tag ...language.Tag) error
- func MustAdd(reader io.Reader, tag ...language.Tag)
- func MustAddFromString(json string, tag ...language.Tag)
- func Reset()
- func Translate(key string, args ...interface{}) string
- type Context
- type Replace
- type Translator
- func Create(reader io.Reader) (*Translator, error)
- func CreateFromString(json string) (*Translator, error)
- func MustCreate(reader io.Reader) *Translator
- func MustCreateFromString(json string) *Translator
- func SelectTranslator(lang string) *Translator
- func SelectTranslatorWithRequest(r *http.Request) *Translator
- type TranslatorFunction
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Add ¶
Add registers dictionary to default Translator instance.
If JSON format is invalid, it returns error.
If tag is specified as 2nd parameter, it registers dictionary to specified language translator. You can access the registered translator with Select, SelectTranslator SelectTranslatorWithRequest, SelectWithRequest functions
func AddFromString ¶
AddFromString registers dictionary to default Translator instance. It is similar to Add, but it accepts string instead of []byte.
If JSON format is invalid, it returns error.
If tag is specified as 2nd parameter, it registers dictionary to specified language translator. You can access the registered translator with Select, SelectTranslator SelectTranslatorWithRequest, SelectWithRequest functions
func AddWord ¶ added in v0.4.0
AddWord adds key and value pair to existing dictionary. It is good for adding long text like email/html templates.
func MustAdd ¶
MustAdd registers dictionary to default Translator instance.
If JSON format is invalid, it makes application panic. It is good for static initialization.
If tag is specified as 2nd parameter, it registers dictionary to specified language translator. You can access the registered translator with Select, SelectTranslator SelectTranslatorWithRequest, SelectWithRequest functions
func MustAddFromString ¶
MustAddFromString registers dictionary to default Translator instance. It is similar to MustAdd, but it accepts string instead of []byte.
If JSON format is invalid, it makes application panic. It is good for static initialization.
If tag is specified as 2nd parameter, it registers dictionary to specified language translator. You can access the registered translator with Select, SelectTranslator SelectTranslatorWithRequest, SelectWithRequest functions
Types ¶
type Replace ¶
type Replace map[string]interface{}
Replace type is used for passing replacement parameters when translating.
type Translator ¶
type Translator struct {
// contains filtered or unexported fields
}
Translator type keeps translation dictionary and provides translation feature.
This instance is created via Create() functions. Or you can use default instance.
func Create ¶
func Create(reader io.Reader) (*Translator, error)
Create returns new Translator instance.
If JSON format is invalid, it returns error.
func CreateFromString ¶
func CreateFromString(json string) (*Translator, error)
CreateFromString returns new Translator instance. It is similar to Create, but it accepts string instead of []byte.
If JSON format is invalid, it returns error.
func MustCreate ¶
func MustCreate(reader io.Reader) *Translator
MustCreate returns new Translator instance.
If JSON format is invalid, it makes application panic. It is good for static initialization.
func MustCreateFromString ¶
func MustCreateFromString(json string) *Translator
MustCreateFromString returns new Translator instance. It is similar to MustCreate, but it accepts string instead of []byte.
If JSON format is invalid, it makes application panic. It is good for static initialization.
func SelectTranslator ¶ added in v0.3.0
func SelectTranslator(lang string) *Translator
SelectTranslator returns Translator instance from registered ones.
func SelectTranslatorWithRequest ¶ added in v0.3.0
func SelectTranslatorWithRequest(r *http.Request) *Translator
func (*Translator) AddWord ¶ added in v0.4.0
func (t *Translator) AddWord(key, value string)
func (*Translator) Translate ¶
func (t *Translator) Translate(text string, args ...interface{}) string
Translate method returns translated text.
You can pass parameters like default text(string), count for pluralisation(int), replacement parameters(i18n4v.Replace), context parameters(i18n4v.Context). You can omit any parameters, but you should keep the order of them.
type TranslatorFunction ¶ added in v0.3.0
TranslatorFunction is a type of translation function
func Select ¶ added in v0.3.0
func Select(lang string) TranslatorFunction
func SelectWithRequest ¶ added in v0.3.0
func SelectWithRequest(r *http.Request) TranslatorFunction