1   Background

./locale/en/LC_MESSAGES
./locale/fr/LC_MESSAGES
./locale/sp/LC_MESSAGES

2   How to create gettext catalog files

To help creating the gettext binary catalog files, I wrote a Python console program called mki18n.py tha uses the GNU gettext utilities to parse Python source code and create the .po and .mo files. The mki18n.py is used to perform several tasks:

• parse all Python source code files of an application and create the .pot file for each target language.
• parse all Python source code files of an application and merge the generated .pot with existing .po (files that already contain text translated by human translator).
• create the binary .mo files from the .po files.

The mki18n.py module can also be used as an imported module inside other Python programs.

3   How to write an internationalized wxPython application

The application must contain the following code:

• the main module must import the gettext module.

• the global code of the main module must call gettext.install() to install the function _() inside the application dictionary. This call identifies the translation domain ⁴ (which normally is the application name), the location of the LC_MESSAGES directories and whether Unicode is used. The following is an example of the call where the dictionary files are under ./locale/xx/LC_MESSAGES (with xx being the language code) and testApp being the name of the application (and the name of the .mo file):

  gettext.install('testApp', './manual', unicode=False)
  

• For each supported presentation language, the program must create a gettext. Translation instance by calling gettext.translation(). The arguments to the translation function are the application domain (the name of the .mo file which is often the name of the application), the directory parent of the languages LC_MESSAGES directories and the list of language. For example, if your application is called ivcm and the files are stored under a directory called locales, the support for English, French and Spanish would be set up by doing the following calls:

  self.presLan_en = gettext.translation("ivcm", "./locale", languages=['en'])
  self.presLan_fr = gettext.translation("ivcm", "./locale", languages=['fr'])
  self.presLan_sp = gettext.translation("ivcm", "./locale", languages=['sp'])
  

• To activate a the translation of your application for a specified language, the language must be activated by calling the Translation.install() method. For example, to activate the French presentation, you would call:

  self.presLan_fr.install()
  

• Set the wxWindows locale by calling wxLocale() and passing the wxLANGUAGE_XX code corresponding to the selected language. The following code snippet shows you how:

  self.locale = wx.Locale(wxLANGUAGE_FRENCH)
  locale.setlocale(locale.LC_ALL, 'FR')
  

• In your code, all strings must be enclosed in a _() call like this:

  aTitle = _("Testing internationalization")
  

The gettext.install(domain, localedir, unicode) call instructs the gettext system to look for the dictionary file name built from the components:

localedir/language/LC_MESSAGES/domain.mo

4   Python and wxPython modules, classes and functions

• Python gettext
• wxPython wx.Locate class
• wxPython wx.GetTranslation()
• Windows wxLocale

5   Controlling the presentation language from the environment variables

The following environment variables control the selection of the translation language. The system uses the language code found in the first environment variable found from the following list:

• LANGUAGE
• LC_ALL
• LC_MESSAGES
• LANG

6   Tools to manage translation dictionary files

I normally use the CRiSP editor to edit .po files and compare several versions of the .po files. There are, however, specialized tools that simplify managing gettext catalog files. These tools are listed here.

• poEdit is a cross-platform gettext catalogs (.po files) editor.

7   Creating .mo files with the mki18n.py script

The mki18n.py script helps you create .po and .mo files from your source code files for an application. I describe the process of internationalizing the ivcm application here.

All strings that must be internationalized inside ivcm.py (and its companion files) have the form _("Hello"). All strings inside the source code must be in English as this is the convention used by the gettext system.

To use my mki18n.py script, I write a file called app.fil that contains the names of all files inside the application (one file per line, with full or relative path. For example:

images.py
ivcm.py
ivcm_about.py
ivcm_ie.py
ivcm_usermanual.py
ivcm_wxFrame1.py
../ptz.py
../action.py
../utprint.py

Then I run mki18n -p from the directory where ivcm.py is located to parse all source files and create a 'messages.pot' file. The .pot is the original template. You keep this file untouched. If I want to support French then I copy the messages.pot into a .po file named after the domain name (in this case the application name: 'ivcm') and the target language code (in this case: 'fr'). So for French I use the file name: ivcm_fr.po. If I need to support Spanish, I copy messages.pot into ivcm_sp.po and so on.

The following lines show a couple of entries inside the non translated ivcm_fr.po:

#: ivcm.py:168
#, python-format
msgid ""
"\n"
"   ERROR: %s"
msgstr ""

#: ivcm_wxFrame1.py:638 ivcm_wxFrame1.py:1742
msgid "&About..."
msgstr ""

The next step is to perform the translation. You can use a normal editor to append the French string inside the ivcm_fr.po or use poEdit or any other .po editor. The result of the translation would look like:

#: ivcm.py:168
#, python-format
msgid ""
"\n"
"   ERROR: %s"
msgstr ""
"\n"
"   ERREUR: %s"

#: ivcm_wxFrame1.py:638 ivcm_wxFrame1.py:1742
msgid "&About..."
msgstr "À propos de iVCM..."

Note that every line with a '#' in the first column is a comment or flag. In the example above the python-format flag shows that the strings were extracted from Python source. The #: lines show the line number of the original source.

Some of the flags are set when you re-synchronyze the translations with the source. This resynchronization is required if the source changes after you have created the translated .po file(s).

My mki18n.py script will automatically perform syncronisation if it finds .po files that have the domain_language.po name layout. After a re-synchronization, 'mki18n -p' creates a .new file for every .po file found. In my example, it would create a ivcm_fr.po.new and a ivcm_sp.po.new

If the source has not changed, the .new files are equal to the .po file. Otherwise, the .new file contains the new strings to translate, place the straing that were removed from the source as comments inside the .po.new file and may also flag some strings as 'fuzzy'. A fuzzy flag indicates that the translation of the original source should probably change because the original string changed. So, I compare the .po and .po.new, and edit whatever is requiered, leaving the finished work inside the .po file.

The final step is to compile the finished .po file into the .mo file.

The .mo file normally reside inside the LC_MESSAGES of a 'locale' sub-directory with a xx/LC_MESSAGES for each supported language:

du locale
         3 locale/en/LC_MESSAGES
      8803 locale/en
       172 locale/fr/LC_MESSAGES
      7997 locale/fr
         4 locale/sp/LC_MESSAGES
        54 locale/sp
     20413 locale

I create the .mo file using mki18n -m which uses the msgfmt.exe tool that comes with the GNU gettext utility.

And then the application uses the .mo file!