pyfa/locale

Pyfa Internationalization(i18n) and Localization(l10n)

Below is a summary of GNU gettext manual, adapted for Pyfa i18n workflow.

Poedit offers a nice GUI for same GNU gettext translation workflow.

i18n with command line

Windows users can get these tools via Git for windows, Msys2 or Cygwin; or just use WSL / WSL2. For Linux and macOS users these tools might be available out-of-box.

To generate new template for translation:

$ find gui/ *.py -name "*.py" | xgettext --from-code=UTF-8 -o locale/lang.pot -d lang -k_t -f - -s

explanation:

• find gui/ *.py -name "*.py": collect all .py file path in gui folder and all sub-folders, write it to stdout
• xgettext: a utility looking for keyword and put string literals in a specific format for human translation
  • --from-code=UTF-8: designates encoding of files
  • -o locale/lang.pot: let xgettext write to locale/lang.pot
  • -d lang: default language domain is lang
  • -k_t: besides default keyword (including _, see info xgettext for detail), also look for _t
  • -f -: let xgettext to read from stdin, which is connected to find stdout
  • -s: sort output according to msgid

this locale/lang.pot is called PO template, which is throwed away once actual ll_CC/LC_MESSAGES/lang.po is ready for use.

To initialize PO file for new language

$ msginit -i locale/lang.pot -l ll_CC -o locale/ll_CC/LC_MESSAGES/lang.po -s

explanation:

• -i locale/lang.pot: input file location
• -l ll_CC: target locale. ll should be a language code, and CC should be a country code
• -o locale/ll_CC/LC_MESSAGES/lang.po: output file
  • ll_CC: same as above
  • LC_MESSAGES: GNU gettext conventional path to search for localized messages
  • lang.po: language domain and file format

this locale/ll_CC/LC_MESSAGES/lang.po should be checked into VCS, later it will be converted into mechine readable format (MO).

To update PO file for existing translation

$ msgmerge -s locale/ll_CC/LC_MESSAGES/lang.po locale/lang.pot

To do actual translation

just edit the lang.po file :)

To generate machine readable MO file

For a single locale:

$ msgfmt locale/ll_CC/LC_MESSAGES/lang.po -o locale/ll_CC/LC_MESSAGES/lang.mo

For all available locale:

for f in locale/*/; do 
    msgfmt $f/LC_MESSAGES/lang.po -o $f/LC_MESSAGES/lang.mo
done

To merge 2 or more PO file

$ msgcat -s path/to/old.po [path/to/another.po] -o path/to/new.po

Note that msgcat cannot perform a 3-way merge, it will simply stack translations with same msgid on top of each other. If you use msgcat to merge multiple PO file, please check and fix the output before commit to Git.

i18n with Poedit

To update PO file for existing translation

1. open a existing locale/ll_CC/LC_MESSAGES/lang.po
2. Catalog -> Update form POT file
3. select pre-prepared lang.pot file

To translate and generate MO file

edit the translation and hit Save :)