i18n

README

Translations README

This is a basic sketch of the workflow needed to add translations:

Adding/Updating Translations

New languages

Create staging/src/k9s.io/kubectl/pkg/util/i18n/translations/kubectl/<language>/LC_MESSAGES/k8s.po. There's no need to update translations/test/... which is only used for unit tests.

There is an example PR here which adds support for French.

Once you've added a new language, you'll need to register it in staging/src/k8s.io/kubectl/pkg/util/i18n/i18n.go by adding it to the knownTranslations map.

Wrapping strings

There is a simple script in staging/src/k8s.io/kubectl/pkg/util/i18n/translations/extract.py that performs simple regular expression based wrapping of strings. It can always use improvements to understand additional strings.

Extracting strings

Once the strings are wrapped, you can extract strings from go files using the go-xgettext command which can be installed with:

go get github.com/gosexy/gettext/go-xgettext

Once that's installed you can run ./hack/update-translations.sh, which will extract and sort any new strings.

Adding new translations

Edit the appropriate k8s.po file, poedit is a popular open source tool for translations. You can load the staging/src/k8s.io/kubectl/pkg/util/i18n/translations/kubectl/template.pot file to find messages that might be missing.

Once you are done with your k8s.po file, generate the corresponding k8s.mo file. poedit does this automatically on save, but you can also run ./hack/update-translations.sh to perform the po to mo translation.

We use the English translation as the msgid.

Regenerating the bindata file

Note: Regeneration of bindata is no more necessary for Kubernetes 1.22+ as the translations are now embedded into the binary at compile time. See: https://github.com/kubernetes/kubernetes/pull/99829

With the mo files up to date, you can now convert the generated files into code using go-bindata command which can be installed with:

go get github.com/go-bindata/go-bindata/...

Run ./hack/generate-bindata.sh, this will turn the translation files into generated code which will in turn be packaged into the Kubernetes binaries.

Extracting strings

There is a script in staging/src/k8s.io/kubectl/pkg/util/i18n/translations/extract.py that knows how to do some simple extraction. It needs a lot of work.

Using translations

To use translations, you simply need to add:

import pkg/i18n
...
// Get a translated string
translated := i18n.T("Your message in english here")

// Get a translated plural string
translated := i18n.T("You had % items", items)

// Translated error
return i18n.Error("Something bad happened")

// Translated plural error
return i18n.Error("%d bad things happened")

Documentation

Index

• Variables
• func Errorf(defaultValue string, args ...int) error
• func LoadTranslations(root string, getLanguageFn func() string) error
• func SetLoadTranslationsFunc(f func() error) error
• func T(defaultValue string, args ...int) string

Variables

var (
	LoadTranslationsFunc = func() error {
		return LoadTranslations("kubectl", nil)
	}
)

Functions

func Errorf

func Errorf(defaultValue string, args ...int) error

Errorf produces an error with a translated error string. Substitution is performed via the `T` function above, following the same rules.

func LoadTranslations

func LoadTranslations(root string, getLanguageFn func() string) error

LoadTranslations loads translation files. getLanguageFn should return a language string (e.g. 'en-US'). If getLanguageFn is nil, then the loadSystemLanguage function is used, which uses the 'LANG' environment variable.

func SetLoadTranslationsFunc

func SetLoadTranslationsFunc(f func() error) error

SetLoadTranslationsFunc sets the function called to lazy load translations. It must be called in an init() func that occurs BEFORE any i18n.T() calls are made by any package. You can accomplish this by creating a separate package containing your init() func, and then importing that package BEFORE any other packages that call i18n.T().

Example Usage:

package myi18n

import "k8s.io/kubectl/pkg/util/i18n"

func init() {
	if err := i18n.SetLoadTranslationsFunc(loadCustomTranslations); err != nil {
		panic(err)
	}
}

func loadCustomTranslations() error {
	// Load your custom translations here...
}

And then in your main or root command package, import your custom package like this:

import (
	// Other imports that don't need i18n...
	_ "example.com/myapp/myi18n"
	// Other imports that do need i18n...
)

func T

func T(defaultValue string, args ...int) string

T translates a string, possibly substituting arguments into it along the way. If len(args) is > 0, args1 is assumed to be the plural value and plural translation is used.