1# Translations README
2
3This is a basic sketch of the workflow needed to add translations:
4
5# Adding/Updating Translations
6
7## New languages
8Create `staging/src/k8s.io/kubectl/pkg/util/i18n/translations/kubectl/<language>/LC_MESSAGES/k8s.po`. There's
9no need to update `translations/test/...` which is only used for unit tests.
10
11There is an example [PR here](https://github.com/kubernetes/kubernetes/pull/40645) which adds support for French.
12
13Once you've added a new language, you'll need to register it in
14`staging/src/k8s.io/kubectl/pkg/util/i18n/i18n.go` by adding it to the `knownTranslations` map.
15
16## Wrapping strings
17There is a simple script in `staging/src/k8s.io/kubectl/pkg/util/i18n/translations/extract.py` that performs
18simple regular expression based wrapping of strings. It can always
19use improvements to understand additional strings.
20
21## Extracting strings
22Once the strings are wrapped, you can extract strings from go files using
23the `go-xgettext` command which can be installed with:
24
25```console
26go get github.com/gosexy/gettext/go-xgettext
27```
28
29Once that's installed you can run `./hack/update-translations.sh`, which
30will extract and sort any new strings.
31
32## Adding new translations
33Edit the appropriate `k8s.po` file, `poedit` is a popular open source tool
34for translations. You can load the `staging/src/k8s.io/kubectl/pkg/util/i18n/translations/kubectl/template.pot` file
35to find messages that might be missing.
36
37Once you are done with your `k8s.po` file, generate the corresponding `k8s.mo`
38file. `poedit` does this automatically on save, but you can also run
39`./hack/update-translations.sh` to perform the `po` to `mo` translation.
40
41We use the English translation as the `msgid`.
42
43## Regenerating the bindata file
44
45> Note: Regeneration of bindata is no more necessary for Kubernetes 1.22+ as
46> the translations are now embedded into the binary at compile time.
47> See: https://github.com/kubernetes/kubernetes/pull/99829
48
49With the `mo` files up to date, you can now convert the generated files
50into code using `go-bindata` command which can be installed with:
51
52```console
53go get github.com/go-bindata/go-bindata/...
54```
55
56Run `./hack/generate-bindata.sh`, this will turn the translation files
57into generated code which will in turn be packaged into the Kubernetes
58binaries.
59
60## Extracting strings
61
62There is a script in `staging/src/k8s.io/kubectl/pkg/util/i18n/translations/extract.py` that knows how to do some
63simple extraction. It needs a lot of work.
64
65# Using translations
66
67To use translations, you simply need to add:
68```go
69import pkg/i18n
70...
71// Get a translated string
72translated := i18n.T("Your message in english here")
73
74// Get a translated plural string
75translated := i18n.T("You had % items", items)
76
77// Translated error
78return i18n.Error("Something bad happened")
79
80// Translated plural error
81return i18n.Error("%d bad things happened")
82```
View as plain text