Awesome
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).
Package i18n
The i18n package provides support for looking up messages according to a set of locale preferences.
import "github.com/nicksnyder/go-i18n/v2/i18n"
Create a Bundle to use for the lifetime of your application.
bundle := i18n.NewBundle(language.English)
Load translations into your bundle during initialization.
bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal)
bundle.LoadMessageFile("es.toml")
// If use go:embed
//go:embed locale.*.toml
var LocaleFS embed.FS
bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal)
bundle.LoadMessageFileFS(LocaleFS, "locale.es.toml")
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.Localize(&i18n.LocalizeConfig{
DefaultMessage: &i18n.Message{
ID: "PersonCats",
One: "{{.Name}} has {{.Count}} cat.",
Other: "{{.Name}} has {{.Count}} cats.",
},
TemplateData: map[string]interface{}{
"Name": "Nick",
"Count": 2,
},
PluralCount: 2,
}) // Nick has 2 cats.
Command goi18n
The goi18n command manages message files used by the i18n package.
go install -v github.com/nicksnyder/go-i18n/v2/goi18n@latest
goi18n -help
Extracting messages
Use goi18n extract
to extract all i18n.Message struct literals in Go source files to a message file for translation.
# active.en.toml
[PersonCats]
description = "The number of cats a person has"
one = "{{.Name}} has {{.Count}} cat."
other = "{{.Name}} has {{.Count}} cats."
Translating a new language
-
Create an empty message file for the language that you want to add (e.g.
translate.es.toml
). -
Run
goi18n merge active.en.toml translate.es.toml
to populatetranslate.es.toml
with the messages to be translated.# translate.es.toml [HelloPerson] hash = "sha1-5b49bfdad81fedaeefb224b0ffc2acc58b09cff5" other = "Hello {{.Name}}"
-
After
translate.es.toml
has been translated, rename it toactive.es.toml
.# active.es.toml [HelloPerson] hash = "sha1-5b49bfdad81fedaeefb224b0ffc2acc58b09cff5" other = "Hola {{.Name}}"
-
Load
active.es.toml
into your bundle.bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal) bundle.LoadMessageFile("active.es.toml")
Translating new messages
If you have added new messages to your program:
- Run
goi18n extract
to updateactive.en.toml
with the new messages. - Run
goi18n merge active.*.toml
to generate updatedtranslate.*.toml
files. - Translate all the messages in the
translate.*.toml
files. - Run
goi18n merge active.*.toml translate.*.toml
to merge the translated messages into the active message files.
For more information and examples:
- Read the documentation.
- Look at the code examples and tests.
- Look at an example application.
Translations of this document
Community translations of this document may be found in the .github folder.
These translations are maintained by the community, and are not maintained by the author of this project. They are not guaranteed to be accurate or up-to-date.
License
go-i18n is available under the MIT license. See the LICENSE file for more info.