1# go-i18n ![Build status](https://github.com/nicksnyder/go-i18n/workflows/Build/badge.svg) [![Report card](https://goreportcard.com/badge/github.com/nicksnyder/go-i18n)](https://goreportcard.com/report/github.com/nicksnyder/go-i18n) [![codecov](https://codecov.io/gh/nicksnyder/go-i18n/branch/master/graph/badge.svg)](https://codecov.io/gh/nicksnyder/go-i18n) [![Sourcegraph](https://sourcegraph.com/github.com/nicksnyder/go-i18n/-/badge.svg)](https://sourcegraph.com/github.com/nicksnyder/go-i18n?badge) 2 3go-i18n is a Go [package](#package-i18n) and a [command](#command-goi18n) that helps you translate Go programs into multiple languages. 4 5- Supports [pluralized strings](http://cldr.unicode.org/index/cldr-spec/plural-rules) for all 200+ languages in the [Unicode Common Locale Data Repository (CLDR)](http://www.unicode.org/cldr/charts/28/supplemental/language_plural_rules.html). 6 - Code and tests are [automatically generated](https://github.com/nicksnyder/go-i18n/tree/master/i18n/language/codegen) from [CLDR data](http://cldr.unicode.org/index/downloads). 7- Supports strings with named variables using [text/template](http://golang.org/pkg/text/template/) syntax. 8- Supports message files of any format (e.g. JSON, TOML, YAML). 9 10## Package i18n [![GoDoc](http://godoc.org/github.com/nicksnyder/go-i18n?status.svg)](http://godoc.org/github.com/nicksnyder/go-i18n/v2/i18n) 11 12The i18n package provides support for looking up messages according to a set of locale preferences. 13 14```go 15import "github.com/nicksnyder/go-i18n/v2/i18n" 16``` 17 18Create a Bundle to use for the lifetime of your application. 19 20```go 21bundle := i18n.NewBundle(language.English) 22``` 23 24Load translations into your bundle during initialization. 25 26```go 27bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal) 28bundle.LoadMessageFile("es.toml") 29``` 30 31Create a Localizer to use for a set of language preferences. 32 33```go 34func(w http.ResponseWriter, r *http.Request) { 35 lang := r.FormValue("lang") 36 accept := r.Header.Get("Accept-Language") 37 localizer := i18n.NewLocalizer(bundle, lang, accept) 38} 39``` 40 41Use the Localizer to lookup messages. 42 43```go 44localizer.Localize(&i18n.LocalizeConfig{ 45 DefaultMessage: &i18n.Message{ 46 ID: "PersonCats", 47 One: "{{.Name}} has {{.Count}} cat.", 48 Other: "{{.Name}} has {{.Count}} cats.", 49 }, 50 TemplateData: map[string]interface{}{ 51 "Name": "Nick", 52 "Count": 2, 53 }, 54 PluralCount: 2, 55}) // Nick has 2 cats. 56``` 57 58## Command goi18n [![GoDoc](http://godoc.org/github.com/nicksnyder/go-i18n?status.svg)](http://godoc.org/github.com/nicksnyder/go-i18n/v2/goi18n) 59 60The goi18n command manages message files used by the i18n package. 61 62``` 63go get -u github.com/nicksnyder/go-i18n/v2/goi18n 64goi18n -help 65``` 66 67### Extracting messages 68 69Use `goi18n extract` to extract all i18n.Message struct literals in Go source files to a message file for translation. 70 71```toml 72# active.en.toml 73[PersonCats] 74description = "The number of cats a person has" 75one = "{{.Name}} has {{.Count}} cat." 76other = "{{.Name}} has {{.Count}} cats." 77``` 78 79### Translating a new language 80 811. Create an empty message file for the language that you want to add (e.g. `translate.es.toml`). 822. Run `goi18n merge active.en.toml translate.es.toml` to populate `translate.es.toml` with the messages to be translated. 83 84 ```toml 85 # translate.es.toml 86 [HelloPerson] 87 hash = "sha1-5b49bfdad81fedaeefb224b0ffc2acc58b09cff5" 88 other = "Hello {{.Name}}" 89 ``` 90 913. After `translate.es.toml` has been translated, rename it to `active.es.toml`. 92 93 ```toml 94 # active.es.toml 95 [HelloPerson] 96 hash = "sha1-5b49bfdad81fedaeefb224b0ffc2acc58b09cff5" 97 other = "Hola {{.Name}}" 98 ``` 99 1004. Load `active.es.toml` into your bundle. 101 102 ```go 103 bundle.RegisterUnmarshalFunc("toml", toml.Unmarshal) 104 bundle.LoadMessageFile("active.es.toml") 105 ``` 106 107### Translating new messages 108 109If you have added new messages to your program: 110 1111. Run `goi18n extract` to update `active.en.toml` with the new messages. 1122. Run `goi18n merge active.*.toml` to generate updated `translate.*.toml` files. 1133. Translate all the messages in the `translate.*.toml` files. 1144. Run `goi18n merge active.*.toml translate.*.toml` to merge the translated messages into the active message files. 115 116## For more information and examples: 117 118- Read the [documentation](http://godoc.org/github.com/nicksnyder/go-i18n/v2). 119- Look at the [code examples](https://github.com/nicksnyder/go-i18n/blob/master/v2/i18n/example_test.go) and [tests](https://github.com/nicksnyder/go-i18n/blob/master/v2/i18n/localizer_test.go). 120- Look at an example [application](https://github.com/nicksnyder/go-i18n/tree/master/v2/example). 121 122## License 123 124go-i18n is available under the MIT license. See the [LICENSE](LICENSE) file for more info. 125