i18n

Documentation

Overview

Package i18n supports string translations with variable substitution and CLDR pluralization. It is intended to be used in conjunction with github.com/nicksnyder/go-i18n/goi18n, although that is not strictly required.

Initialization

Your Go program should load translations during its intialization.

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 locale. The TranslateFunc will be bound to the first valid locale passed to Tfunc.

userLocale = "ar-AR"     // user preference, accept header, language cookie
defaultLocale = "en-US"  // known valid locale
T, err := i18n.Tfunc(userLocale, defaultLocale)
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("program_greeting")

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",
})

Compound plural strings can be created 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

• func AddTranslation(locale *locale.Locale, translations ...translation.Translation)
• func LoadTranslationFile(filename string) error
• func MustLoadTranslationFile(filename string)
• type TranslateFunc
  • func IdentityTfunc() TranslateFunc
  • func MustTfunc(localeID string, localeIDs ...string) TranslateFunc
  • func Tfunc(localeID string, localeIDs ...string) (TranslateFunc, error)

Examples

• Package
• Package (Template)

Functions

func AddTranslation

func AddTranslation(locale *locale.Locale, translations ...translation.Translation)

AddTranslation adds translations for a locale.

It is useful if your translations are in a format not supported by LoadTranslationFile.

func LoadTranslationFile

func LoadTranslationFile(filename string) error

LoadTranslationFile loads the translations from filename into memory.

The locale that the translations are associated with is parsed from the filename.

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

type TranslateFunc func(translationID string, args ...interface{}) string

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(localeID string, localeIDs ...string) TranslateFunc

MustTfunc is similar to Tfunc except it panics if an error happens.

func Tfunc

func Tfunc(localeID string, localeIDs ...string) (TranslateFunc, error)

Tfunc returns a TranslateFunc that will be bound to the first valid locale from its parameters.