The highest tagged major version is
Documentation
¶
Overview ¶
Package i18n supports string translations with variable substitution and CLDR pluralization. It is intended to be used in conjunction with the goi18n command, although that is not strictly required.
Initialization ¶
Your Go program should load translations during its initialization.
i18n.MustLoadTranslationFile("path/to/fr-FR.all.json")
If your translations are in a file format not supported by (Must)?LoadTranslationFile, then you can use the AddTranslation function to manually add translations.
Fetching a translation ¶
Use Tfunc or MustTfunc to fetch a TranslateFunc that will return the translated string for a specific language.
func handleRequest(w http.ResponseWriter, r *http.Request) {
cookieLang := r.Cookie("lang")
acceptLang := r.Header.Get("Accept-Language")
defaultLang = "en-US" // known valid language
T, err := i18n.Tfunc(cookieLang, acceptLang, defaultLang)
fmt.Println(T("Hello world"))
}
Usually it is a good idea to identify strings by a generic id rather than the English translation, but the rest of this documentation will continue to use the English translation for readability.
T("Hello world") // ok
T("programGreeting") // better!
Variables ¶
TranslateFunc supports strings that have variables using the text/template syntax.
T("Hello {{.Person}}", map[string]interface{}{
"Person": "Bob",
})
Pluralization ¶
TranslateFunc supports the pluralization of strings using the CLDR pluralization rules defined here: http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
T("You have {{.Count}} unread emails.", 2)
T("I am {{.Count}} meters tall.", "1.7")
Plural strings may also have variables.
T("{{.Person}} has {{.Count}} unread emails", 2, map[string]interface{}{
"Person": "Bob",
})
Sentences with multiple plural components can be supported with nesting.
T("{{.Person}} has {{.Count}} unread emails in the past {{.Timeframe}}.", 3, map[string]interface{}{
"Person": "Bob",
"Timeframe": T("{{.Count}} days", 2),
})
Templates ¶
You can use the .Funcs() method of a text/template or html/template to register a TranslateFunc for usage inside of that template.
Example ¶
package main
import (
"fmt"
"github.com/nicksnyder/go-i18n/i18n"
)
func main() {
i18n.MustLoadTranslationFile("../goi18n/testdata/expected/en-us.all.json")
T, _ := i18n.Tfunc("en-US")
fmt.Println(T("program_greeting"))
fmt.Println(T("person_greeting", map[string]interface{}{
"Person": "Bob",
}))
fmt.Println(T("your_unread_email_count", 0))
fmt.Println(T("your_unread_email_count", 1))
fmt.Println(T("your_unread_email_count", 2))
fmt.Println(T("my_height_in_meters", "1.7"))
fmt.Println(T("person_unread_email_count", 0, map[string]interface{}{
"Person": "Bob",
}))
fmt.Println(T("person_unread_email_count", 1, map[string]interface{}{
"Person": "Bob",
}))
fmt.Println(T("person_unread_email_count", 2, map[string]interface{}{
"Person": "Bob",
}))
fmt.Println(T("person_unread_email_count_timeframe", 3, map[string]interface{}{
"Person": "Bob",
"Timeframe": T("d_days", 0),
}))
fmt.Println(T("person_unread_email_count_timeframe", 3, map[string]interface{}{
"Person": "Bob",
"Timeframe": T("d_days", 1),
}))
fmt.Println(T("person_unread_email_count_timeframe", 3, map[string]interface{}{
"Person": "Bob",
"Timeframe": T("d_days", 2),
}))
}
Output: Hello world Hello Bob You have 0 unread emails. You have 1 unread email. You have 2 unread emails. I am 1.7 meters tall. Bob has 0 unread emails. Bob has 1 unread email. Bob has 2 unread emails. Bob has 3 unread emails in the past 0 days. Bob has 3 unread emails in the past 1 day. Bob has 3 unread emails in the past 2 days.
Example (Template) ¶
package main
import (
"github.com/nicksnyder/go-i18n/i18n"
"os"
"text/template"
)
var funcMap = map[string]interface{}{
"T": i18n.IdentityTfunc,
}
var tmpl = template.Must(template.New("").Funcs(funcMap).Parse(`
{{T "program_greeting"}}
{{T "person_greeting" .}}
{{T "your_unread_email_count" 0}}
{{T "your_unread_email_count" 1}}
{{T "your_unread_email_count" 2}}
{{T "person_unread_email_count" 0 .}}
{{T "person_unread_email_count" 1 .}}
{{T "person_unread_email_count" 2 .}}
`))
func main() {
i18n.MustLoadTranslationFile("../goi18n/testdata/expected/en-us.all.json")
T, _ := i18n.Tfunc("en-US")
tmpl.Funcs(map[string]interface{}{
"T": T,
})
tmpl.Execute(os.Stdout, map[string]interface{}{
"Person": "Bob",
"Timeframe": T("d_days", 1),
})
}
Output: Hello world Hello Bob You have 0 unread emails. You have 1 unread email. You have 2 unread emails. Bob has 0 unread emails. Bob has 1 unread email. Bob has 2 unread emails.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddTranslation ¶
func AddTranslation(lang *language.Language, translations ...translation.Translation)
AddTranslation adds translations for a language.
It is useful if your translations are in a format not supported by LoadTranslationFile.
func LoadTranslationFile ¶
LoadTranslationFile loads the translations from filename into memory.
The language that the translations are associated with is parsed from the filename (e.g. en-US.json).
Generally you should load translation files once during your program's initialization.
func MustLoadTranslationFile ¶
func MustLoadTranslationFile(filename string)
MustLoadTranslationFile is similar to LoadTranslationFile except it panics if an error happens.
Types ¶
type TranslateFunc ¶
TranslateFunc returns the translation of the string identified by translationID.
If translationID is a non-plural form, then the first variadic argument may be a map[string]interface{} that contains template data.
If translationID is a plural form, then the first variadic argument must be an integer type (int, int8, int16, int32, int64) or a float formatted as a string (e.g. "123.45"). The second variadic argument may be a map[string]interface{} that contains template data.
func IdentityTfunc ¶
func IdentityTfunc() TranslateFunc
IdentityTfunc returns a TranslateFunc that always returns the translationID passed to it.
It is a useful placeholder when parsing a text/template or html/template before the actual Tfunc is available.
func MustTfunc ¶
func MustTfunc(languageSource string, languageSources ...string) TranslateFunc
MustTfunc is similar to Tfunc except it panics if an error happens.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bundle manages translations for multiple languages.
|
Package bundle manages translations for multiple languages. |
|
Package language defines languages that implement CLDR pluralization.
|
Package language defines languages that implement CLDR pluralization. |
|
Package translation defines the interface for a translation.
|
Package translation defines the interface for a translation. |