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