Project: KusionStack (Provisioning / Automation & Configuration)
File: README.md

Based on GNU gettext, kusion implements support for internationalization(i18n). There is basic sketch of the workflow of using and updating/adding translations. To use translations, you must use the convention syntax to write strings in source codes, i.e. the .go files. There are two funcs provided, `i18n.T` and `i18n.Error`. ```go import "kusionstack.io/kusion/pkg/util/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") ``` In kusion, translations are used for cmd, including `short description`, `long description`, `example`, `flag description`. There are some conventions when using translations: The translation string must be a sentence, and start with capital letter; For `short description` and `flag description`, the sentence must end without full stop. For `long description`, must end with full stop. For `example`, it depends on the semantic; Use func `i18n.T` without plural translation in usual, and the package name must be `i18n`. If func `i18n.Error` is in use, should update `hack/update-translations.sh`; When using `i18n.T`, the input string must be a const, variable is not allowed, which is the restriction of `go-xgettext`; Be sure that `i18n.T` will be executed, don't use `i18n.T` to create a global variables, which is generated when compiling; When using back quote to define a string, write a paragraph in one line without line break, or there is unexpected space in translations. When a line break is needed, the new line should start with two tabs; When new commands added, update `CMD_FILES` in `hack/update-translations.sh`. Refer to `pkg/cmd/init/init.go`, which is an example to show how to use i18n. GNU gettext realizes i18n based on three files: `.pot`, `.po`, `.mo`. There are usages: `.pot` is the template file, used to extract i18n strings from `.go` source codes; `.po` is for human translator. `.pot` can generate the template of

for different languages, and then translator translates and save the result in `.po`; `.mo` is for machine using. `.mo` is generated by `.po` and paired with `.po`. In kusion, two languages is supported for now, `enUS` and `zhCN`, where the former is the default language. The `.pot` is `pkg/util/i18n/translations/kusion/template.pot`, the `.po` is `pkg/util/i18n/translations/kusion/<language>/LC_MESSAGES/kusion.po`, and the `.mo` is `pkg/util/i18n/translations/kusion/<language>/LC_MESSAGES/kusion.mo`. `pkg/util/i18n/translations/test` is for testing, do not edit it. `go-xgettext` is used to extract `.pot` from `.go` files, and `msgmerge` is used to update the template of `.po`. First, install the commands: ```console go install github.com/gosexy/gettext/go-xgettext brew install gettext ``` Then, run `hack/update-translations.sh` under repo root path, to update the `.pot` file and the templates of `.po` files. After executing the script, you will find the `msgid` updated but left `msgstr` empty in `.po`. Now, You need to do the translation job, translate the `msgid` in `en_US` to `msgstr` in the specified language. `poedit` is a popular open source tool for translations. You can load the `.po` file, add or update the translations. When finishing translating and save `.po` file, the corresponding `.mo` file with same prefix in the same directory will get updated automatically by `poedit`. If you don't want to use `poedit`, after updating `.po`, you have to update `.mo` manually. You can use the following command, run under the corresponding language's translation dir: ```console msgfmt -c -v -o kusion.mo kusion.po ``` Because there is no need to do translation for default language `en_US`, `hack/update-translations.sh` updates `.mo` for `en_US`. Hence, you don't need to do any job for `.po` and `.mo` for `en_US` at all. When the above jobs are done, `i18n` will work for the software. But in kusion, you need to update the docs, run `hack/gen-docs/main.go` to update the docs under `docs/cmd`. You can specify the doc directory and language env key by args, which is in usual not needed. Which is similar to the above steps, the only thing is to update `knownTranslations` in `pkg/util/i18n/i18n.go`, `TRANSLATIONS_LANG` in `hack/update-translations.sh`, `docsMatrix` in `hack/gen-docs/main.go`.