i18n

Overview ¶

Package i18n offers the following basic internationalization functionality:

• message translation
• with placeholder support
• with plural support
• number formatting
• with currency support
• with percentage support
• locale-aware string sorting

There's more we'd like to add in the future, including:

• datetime formatting
• ordinals
• CLDR xml to yaml rules generation
• data caching with size limitations
• nestable message categories
• small-string number formatting
• 7m : about 7 million
• 1.2k : about 1,200
• 253 : exactly 253
• 25b : about 25 billion
• etc.
• out-of-the-box CLDR messages
• date/time units
• calendar/month/day names
• languages
• geographic region and country names
• currencies
• etc.

How the i18n Package Works ¶

In order to interact with this package, you must first get a TranslatorFactory instace. Through the TranslatorFactory, you can get a Translator instance. Almost everything in this package is accessed through methods on the Translator struct.

About the rules and messages paths: This package ships with built-in rules, and you are welcome to use those directly. However, if there are locales or rules that are missing from what ships directly with this package, or if you desire to use different rules than those that ship with this package, then you can specify additional rules paths. At this time, this package does not ship with built-in messages, other than a few used for the unit tests. You will need to specify your own messages path(s). For both rules and messages paths, you can specify multiple. Paths later in the slice take precedence over packages earlier in the slice.

For a basic example of getting a TranslatorFactory instance:

func main() {

	rulesPath := "/usr/local/lib/i18n/locales/rules"
	messagesPath := "/usr/local/lib/i18n/locales/messages"

	f, _ := i18n.NewTranslatorFactory(
		[]string{rulesPath},
		[]string{messagesPath},
		"en",
	)

	tEn, _ := i18n.GetTranslator("en")

	_ = tEn
}

Simple Message Translation ¶

For simple message translation, use the Translate function, and send an empty map as the second argument (we'll explain that argument in the next section).

func main() {

	rulesPath := "/usr/local/lib/i18n/locales/rules"
	messagesPath := "/usr/local/lib/i18n/locales/messages"

	f, _ := i18n.NewTranslatorFactory(
		[]string{rulesPath},
		[]string{messagesPath},
		"en",
	)

	tEn, _ := i18n.GetTranslator("en")

	// WELCOME_MSG => "Welcome!"
	translation, _ := tEn.Translate("WELCOME_MSG", map[string]string{})

	_ = translation
}

Message Translation with Placeholders ¶

You can also pass placeholder values to the translate function. That's what the second argument is for. In this example, we will inject a username into the translation.

func main() {

	rulesPath := "/usr/local/lib/i18n/locales/rules"
	messagesPath := "/usr/local/lib/i18n/locales/messages"

	f, _ := i18n.NewTranslatorFactory(
		[]string{rulesPath},
		[]string{messagesPath},
		"en",
	)

	tEn, _ := i18n.GetTranslator("en")

	// WELCOME_USER => "Welcome, {user}!"
	username := "Mother Goose"
	translation, _ := tEn.Translate("WELCOME_USER", map[string]string{
		"user" : username
	})

	// results in "Welcome, Mother Goose!"

	_ = translation
}

Plural Message Translation ¶

You can also translate strings with plurals. However, any one message can contain at most one plural. If you want to translate "I need 5 apples and 3 oranges" you are out of luck.

The Pluralize method takes 3 arguments. The first is the message key - just like the Translate method. The second argument is a float which is used to determine which plural form to use. The third is a string representation of the number. Why two arguments for the number instead of one? This allows you ultimate flexibility in number formatting to use in the translation while eliminating the need for string number parsing.

func main() {

	rulesPath := "/usr/local/lib/i18n/locales/rules"
	messagesPath := "/usr/local/lib/i18n/locales/messages"

	f, _ := i18n.NewTranslatorFactory(
		[]string{rulesPath},
		[]string{messagesPath},
		"en",
	)

	tEn, _ := i18n.GetTranslator("en")

	// DAYS_AGO => "{n} day ago|{n} days ago"
	translation1, _ := tEn.Pluralize("DAYS_AGO", 1, "1")
	translation2, _ := tEn.Pluralize("DAYS_AGO", 2, "two")

	// results in "1 day ago" and "two days ago"

	_ = translation1
	_ = translation2
}

Number Formatting ¶

You can use the "FomatNumber", "FormatCurrency" and "FormatPercent" methods to do locale-based number formatting for numbers, currencies and percentages.

func main() {

	rulesPath := "/usr/local/lib/i18n/locales/rules"
	messagesPath := "/usr/local/lib/i18n/locales/messages"

	f, _ := i18n.NewTranslatorFactory(
		[]string{rulesPath},
		[]string{messagesPath},
		"en",
	)

	tEn, _ := i18n.GetTranslator("en")

	number := float64(1234.5678)
	numberStr := tEn.FormatNumber(number)
	currencyStr := tEn.FormatCurrency(number, "USD")
	percentStr := tEn.FormatPercent(number)

	// results in 1,234.567, $1,234.56, 123,456%

	_ = numberStr
	_ = currencyStr
	_ = percentStr
}

Alphabetic String Sorting ¶

If you need to sort a list of strings alphabetically, then you should not use a simple string comparison to do so - this will often result in incorrect results. "ȧ" would normally evaluate as greater than "z", which is not correct in any latin writing system alphabet. Use can use the Sort method on the Translator struct to do an alphabetic sorting that is correct for that locale. Alternatively, you can access the SortUniversal and the SortLocale functions directly without a Translator instance. SortUniversal does not take a specific locale into account when doing the alphabetic sorting, which means it might be slightly less accurate than the SortLocal function. However, there are cases in which the collation rules for a specific locale are unknown, or the sorting needs to be done in a local-agnostic way. For these cases, the SortUniversal function performs a unicode normalization in order to best sort the strings.

In order to be flexible, these functions take a generic interface slice and a function for retrieving the value on which to perform the sorting. For example:

type Food struct {
	Name string
}

func main() {

	rulesPath := "/usr/local/lib/i18n/locales/rules"
	messagesPath := "/usr/local/lib/i18n/locales/messages"

	f, _ := i18n.NewTranslatorFactory(
		[]string{rulesPath},
		[]string{messagesPath},
		"en",
	)

	tEn, _ := i18n.GetTranslator("en")

	toSort := []interface{}{
		Food{Name: "apple"},
		Food{Name: "beet"},
		Food{Name: "carrot"},
		Food{Name: "ȧpricot"},
		Food{Name: "ḃanana"},
		Food{Name: "ċlementine"},
	}

	tEn.Sort(toSort1, func(i interface{}) string {
		if food, ok := i.(Food); ok {
			return food.Name
		}
		return ""
	})

	// results in "apple", "ȧpricot", "ḃanana", "beet", "carrot", "ċlementine"

	// Can also do this:
	i18n.SortLocal("en", toSort1, func(i interface{}) string {
		if food, ok := i.(Food); ok {
			return food.Name
		}
		return ""
	})

	// Or this:
	i18n.SortUniversal(toSort1, func(i interface{}) string {
		if food, ok := i.(Food); ok {
			return food.Name
		}
		return ""
	})

	_ = toSort
}

Fallback Translators ¶

When getting a Translator instance, the TranslatorFactory will automatically attempt to determine an appropriate fallback Translator for the locale you specify. For locales with specific "flavors", like "en-au" or "zh-hans", the "vanilla" version of that locale will be used if it exists. In these cases that would be "en" and "zh".

When creating a TranslatorFactory instance, you can optionally specify a final fallback locale. This will be used if it exists.

When determining a fallback, the the factory first checks the less specific versions of the specified locale, if they exist and will ultimate fallback to the global fallback if specified.

func main() {

	rulesPath := "/usr/local/lib/i18n/locales/rules"
	messagesPath := "/usr/local/lib/i18n/locales/messages"

	f, _ := i18n.NewTranslatorFactory(
		[]string{rulesPath},
		[]string{messagesPath},
		"en",
	)

	tEn, _ := i18n.GetTranslator("en") // no fallback

	tPt, _ := i18n.GetTranslator("pt") // fallback is "en"

	tPtBr, _ := i18n.GetTranslator("pt-br") // fallback is "pt"

	_, _, _ = tEn, tPt, tPtBr
}

Handling Errors ¶

All of the examples above conveniently ignore errors. We recommend that you DO handle errors. The system is designed to give you a valid result if at all possible, even in errors occur in the process. However, the errors are still returned and may provide you helpful information you might otherwise miss - like missing files, file permissions problems, yaml format problems, missing translations, etc. We recommend that you do some sort of logging of these errors.

func main() {

	f, errs := i18n.NewTranslatorFactory(
		[]string{rulesPath},
		[]string{messagesPath},
		"en",
	)

	for _, err := range errs {
		Log(err)
	}

	tEn, errs := i18n.GetTranslator("en")

	for _, err := range errs {
		Log(err)
	}

	translation1, err := tEn.Translate("WELCOME_MSG", map[string]string{})

	for _, err := range errs {
		Log(err)
	}

	translation2, err := tEn.Pluralize("DAYS_AGO", 1, "1")

	for _, err := range errs {
		Log(err)
	}

	number := float64(1234.5678)
	currencyStr, err := tEn.FormatCurrency(number, "USD")

	if err != nil {
		Log(err)
	}

	_ = translation1
	_ = translation2
	_ = currencyStr
}