README.md

go-i18n

go-i18n is a Go package and a command that helps you translate Go programs into multiple languages.

• Supports pluralized strings for all 200+ languages in the Unicode Common Locale Data Repository (CLDR).
  • Code and tests are automatically generated from CLDR data
• Supports strings with named variables using text/template syntax.
• Supports message files of any format (e.g. JSON, TOML, YAML, etc.).
• Documented and tested!

Versions

• v1 is available at 1.x.x tags.
• v2 is available at 2.x.x tags.

This README always documents the latest version (i.e. v2).

Package i18n

The i18n package provides support for looking up messages according to a set of locale preferences.

import "github.com/Vivino/go-i18n/v2/i18n"

Create a Bundle to use for the lifetime of your application.

bundle := &i18n.Bundle{DefaultLanguage: language.English}

Create a Localizer to use for a set of language preferences.

func(w http.ResponseWriter, r *http.Request) {
    lang := r.FormValue("lang")
    accept := r.Header.Get("Accept-Language")
    localizer := i18n.NewLocalizer(bundle, lang, accept)
}

Use the Localizer to lookup messages.

localizer.MustLocalize(&i18n.LocalizeConfig{
    DefaultMessage: &i18n.Message{
        ID: "PersonCats",
        One: "{{.Name}} has {{.Count}} cat.",
        Other: "{{.Name}} has {{.Count}} cats.",
    },
    TemplateData: map[string]string{
        "Name": "Nick",
        "Count": 2,
    },
    PluralCount: 2,
}) // Nick has 2 cats.

It requires Go 1.9 or newer.

Command goi18n

The goi18n command manages message files used by the i18n package.

go get -u github.com/Vivino/go-i18n/v2/goi18n
goi18n -help

Use goi18n extract to create a message file that contains the messages defined in your Go source files.

# en.toml
[PersonCats]
description = "The number of cats a person has"
one = "{{.Name}} has {{.Count}} cat."
other = "{{.Name}} has {{.Count}} cats."

Use goi18n merge to create message files for translation.

# translate.es.toml
[PersonCats]
description = "The number of cats a person has"
hash = "sha1-f937a0e05e19bfe6cd70937c980eaf1f9832f091"
one = "{{.Name}} has {{.Count}} cat."
other = "{{.Name}} has {{.Count}} cats."

Use goi18n merge to merge translated message files with your existing message files.

# active.es.toml
[PersonCats]
description = "The number of cats a person has"
hash = "sha1-f937a0e05e19bfe6cd70937c980eaf1f9832f091"
one = "{{.Name}} tiene {{.Count}} gato."
other = "{{.Name}} tiene {{.Count}} gatos."

Load the active messages into your bundle.

bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal)
bundle.MustLoadMessageFile("active.es.toml")

For more information and examples:

• Read the documentation.
• Look at the code examples and tests.
• Look at an example application.

License

go-i18n is available under the MIT license. See the LICENSE file for more info.