i18n

README

Translation and Internationalization in aks-engine

The translation process in aks-engine borrows some approach from Kubernetes translation. The strings to be localized are mainly the error message strings under pkg directory. Those error message strings are also consumed by other components such as ACS RP.

The localization in aks-engine depends on github.com/leonelquinteros/gotext, a GNU gettext utility for Go. The package supports concurrency in translating strings in multiple goroutines, e.g., the same aks-engine API called from multiple requests at the same time.

The translation files containing resource strings are packaged into aks-engine binary using go-bindata. At runtime, the translation files are recreated on disk in the same directory as aks-engine binary, for gotext to load.

How to add new string to be localized

When a new error string needs to be localized, it needs to use translation function Errorf in pkg/i18n/i18n.go. The locale is passed to aks-engine API from aks-engine command or any other component calls it. If the locale is nil, then it falls back to en-us as in the Go source file.

Once the Go source file is modified, scripts/update-translation.sh needs to be run to extract the resource strings. The script generates PO file according to the locale specified. An example of running the script is:

scripts/update-translation.sh -l en_US -p

poedit is a common tool for translation. After the PO files are translated, MO files can be generated by either poedit or tool such as msgfmt. Both PO file and MO file need to be placed under translations/<locale>/LC_MESSAGES/.

How to add a new language

When the resource strings need to be translated into a new language, the following steps are needed:

1. Use scripts/update-translation.sh with the language to genreate PO file
2. Translate the PO file and generate MO file.
3. Place PO file and MO file under `translations/<language>/LC_MESSAGES/` and commit

Documentation

Overview

Package i18n contains localized strings for user facing messages.

Code generated for package i18n by go-bindata DO NOT EDIT. (@generated) sources: ../../translations/cs_CZ/LC_MESSAGES/acsengine.mo ../../translations/cs_CZ/LC_MESSAGES/acsengine.po ../../translations/de_DE/LC_MESSAGES/acsengine.mo ../../translations/de_DE/LC_MESSAGES/acsengine.po ../../translations/en_US/LC_MESSAGES/acsengine.mo ../../translations/en_US/LC_MESSAGES/acsengine.po ../../translations/en_US/LC_MESSAGES/acsengine.po.lcg ../../translations/en_US/LC_MESSAGES/en-US/lcl/acsengine.po.lcl ../../translations/en_US/LC_MESSAGES/en-US/metadata/acsengine.po.xml ../../translations/es_ES/LC_MESSAGES/acsengine.mo ../../translations/es_ES/LC_MESSAGES/acsengine.po ../../translations/fr_FR/LC_MESSAGES/acsengine.mo ../../translations/fr_FR/LC_MESSAGES/acsengine.po ../../translations/hu_HU/LC_MESSAGES/acsengine.mo ../../translations/hu_HU/LC_MESSAGES/acsengine.po ../../translations/it_IT/LC_MESSAGES/acsengine.mo ../../translations/it_IT/LC_MESSAGES/acsengine.po ../../translations/ja_JP/LC_MESSAGES/acsengine.mo ../../translations/ja_JP/LC_MESSAGES/acsengine.po ../../translations/ko_KR/LC_MESSAGES/acsengine.mo ../../translations/ko_KR/LC_MESSAGES/acsengine.po ../../translations/nl_NL/LC_MESSAGES/acsengine.mo ../../translations/nl_NL/LC_MESSAGES/acsengine.po ../../translations/pl_PL/LC_MESSAGES/acsengine.mo ../../translations/pl_PL/LC_MESSAGES/acsengine.po ../../translations/pt_BR/LC_MESSAGES/acsengine.mo ../../translations/pt_BR/LC_MESSAGES/acsengine.po ../../translations/pt_PT/LC_MESSAGES/acsengine.mo ../../translations/pt_PT/LC_MESSAGES/acsengine.po ../../translations/ru_RU/LC_MESSAGES/acsengine.mo ../../translations/ru_RU/LC_MESSAGES/acsengine.po ../../translations/sv_SE/LC_MESSAGES/acsengine.mo ../../translations/sv_SE/LC_MESSAGES/acsengine.po ../../translations/tr_TR/LC_MESSAGES/acsengine.mo ../../translations/tr_TR/LC_MESSAGES/acsengine.po ../../translations/zh_CN/LC_MESSAGES/acsengine.mo ../../translations/zh_CN/LC_MESSAGES/acsengine.po ../../translations/zh_TW/LC_MESSAGES/acsengine.mo ../../translations/zh_TW/LC_MESSAGES/acsengine.po

Index

• func Asset(name string) ([]byte, error)
• func AssetDir(name string) ([]string, error)
• func AssetInfo(name string) (os.FileInfo, error)
• func AssetNames() []string
• func GetLanguage() string
• func Initialize(locale *gotext.Locale) error
• func LoadTranslations() (*gotext.Locale, error)
• func MustAsset(name string) []byte
• func RestoreAsset(dir, name string) error
• func RestoreAssets(dir, name string) error
• func SetLanguage(language string)
• type Translator
  • func (t *Translator) Errorf(msgid string, vars ...interface{}) error
  • func (t *Translator) NErrorf(msgid, msgidPlural string, n int, vars ...interface{}) error
  • func (t *Translator) NT(msgid, msgidPlural string, n int, vars ...interface{}) string
  • func (t *Translator) T(msgid string, vars ...interface{}) string

Functions

func Asset

func Asset(name string) ([]byte, error)

Asset loads and returns the asset for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetDir

func AssetDir(name string) ([]string, error)

AssetDir returns the file names below a certain directory embedded in the file by go-bindata. For example if you run go-bindata on data/... and data contains the following hierarchy:

data/
  foo.txt
  img/
    a.png
    b.png

then AssetDir("data") would return []string{"foo.txt", "img"} AssetDir("data/img") would return []string{"a.png", "b.png"} AssetDir("foo.txt") and AssetDir("notexist") would return an error AssetDir("") will return []string{"data"}.

func AssetInfo

func AssetInfo(name string) (os.FileInfo, error)

AssetInfo loads and returns the asset info for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetNames

func AssetNames() []string

AssetNames returns the names of the assets.

func GetLanguage

func GetLanguage() string

GetLanguage queries the program's current locale.

func Initialize

func Initialize(locale *gotext.Locale) error

Initialize is the translation initialization function shared by the main program and package.

func LoadTranslations

func LoadTranslations() (*gotext.Locale, error)

LoadTranslations loads translation files and sets the locale to the system locale. It should be called by the main program.

func MustAsset

func MustAsset(name string) []byte

MustAsset is like Asset but panics when Asset would return an error. It simplifies safe initialization of global variables.

func RestoreAsset

func RestoreAsset(dir, name string) error

RestoreAsset restores an asset under the given directory

func RestoreAssets

func RestoreAssets(dir, name string) error

RestoreAssets restores an asset under the given directory recursively

func SetLanguage

func SetLanguage(language string)

SetLanguage sets the program's current locale. If the language is not supported, then the default locale is used.

Types

type Translator

type Translator struct {
	Locale *gotext.Locale
}

Translator is a wrapper over gotext's Locale and provides interface to translate text string and produce translated error

func (*Translator) Errorf

func (t *Translator) Errorf(msgid string, vars ...interface{}) error

Errorf produces an error with a translated error string.

func (*Translator) NErrorf

func (t *Translator) NErrorf(msgid, msgidPlural string, n int, vars ...interface{}) error

NErrorf produces an error with a translated error string in the appropriate plural form.

func (*Translator) NT

func (t *Translator) NT(msgid, msgidPlural string, n int, vars ...interface{}) string

NT translates a text string into the appropriate plural form, based on GNU's gettext library.

func (*Translator) T

func (t *Translator) T(msgid string, vars ...interface{}) string

T translates a text string, based on GNU's gettext library.