Localization Notes

Here are my notes from trying to localize Chandler in French. I'm following a process outlined by Brian Kirsch and will take as many notes as possible here in order to make the work of other localizers easier. The objective is to use these notes as a springboard for a future localizer's doc.

This is being written from the viewpoint of somewhat knowledgeable in computer techniques but not in Python, eggs, Chandler's internals and related technologies...

This page is in support of bug 6657 : Proof-of-concept localization of Chandler and HOWTO document

Localizing Chandler

Getting started

Localization (l10n) is the process of creating translation strings for all the strings displayed in the User Interface of a program.

Chandler is using the GNU gettext() approach, which means that instead of having a resources file with ID numbers, Chandler is using a translation mechanism that maps strings in the code to strings given in a translation dictionary. Localizing is the action of creating such a dictionary.

For this to work, you first need to get the original Chandler source code. See getting Chandler's source code.

In the source code, you'll find 2 tools that will help you handling the translation process:

• $CHANDLERHOME/tools/createPot.py
• $CHANDLERHOME/tools/createTranslationEgg.py

Note that those tools need to be launched from a command line shell (Terminal on Mac OS X, whatever on Windows...). This documentation assumes that you are able to launch such a shell and are somewhat familiar with using the command line interface.

createPot

This tool parses Python source code and wx XRC files for localizable strings and create a ".pot" file. After the tool has been run, the resulting ".pot" file contains all the localizable strings.

createPot can be used on Chandler, Chandler-Example parcels, or a custom 3rd party parcel. The tool ships with defaults for Chandler and Chandler-Examples.

To run createPot, the $CHANDLERHOME environment variable must be set or the tool must be run from the $CHANDLERHOME directory. If the $CHANDLERHOME environment variable is set, the tool can be run from any current working directory.

Chandler Localization

To grab all localizable strings for Chandler, run createPot with the -c flag:

./tools/createPot.py -c

or:

./release/RunPython tools/createPot.py -c

This will create a gettext template file, Chandler.pot, in the current working directory containing all localizable strings for Chandler.

Chandler-Examples Localization

Chandler-Examples is composed of the sample egg parcels under the $CHANDLERHOME/projects directory.

The Example parcels are:

• Chandler-AmazonPlugin
• Chandler-EVDBPlugin
• Chandler-EventLoggerPlugin
• Chandler-FeedsPlugin
• Chandler-FlickrPlugin
• Chandler-PhotoPlugin

To grab all localizable strings for the Chandler-Examples run createPot with the -e flag:

./tools/createPot.py -e

or:

./release/RunPython tools/createPot.py -e

This will create a gettext template file, ChandlerExamples.pot, in the current working directory containing all localizable strings for the Chandler-Example egg parcels.

3rd Party Parcel localization

To localize a 3rd party parcel, createPot has two command line arguments:

• -pPROJECT aka --project=PROJECT: Extracts the localization strings from Python and XRC files for the given project. A gettext .pot template file PROJECTNAME.pot is written to the current working directory.
• -dDIRECTORY aka --directory=DIRECTORY: The root directory to search under for XRC and Python files. Can only be used in conjunction with the -p Project command.

To grab all localizable strings for a parcel named MyParcel in the directory /MyParcel, run createPot with the following commands:

./tools/createPot.py -p MyParcel -d /MyParcel

or:

./release/RunPython tools/createPot.py -p MyParcel -d /MyParcel

This will create a gettext template file MyParcel.pot in the current working directory.

createTranslationEgg

The createTranslationEgg tool builds a separate egg that contains a localization for another egg or grouping of eggs. A localization can include images, html, and text. Like for the createPot tool, defaults are provided for working with Chandler and the Chandler-Example egg parcels.

createTranslationEgg performs the following steps:

• 1. Creates a root directory for the egg
• 2. Creates a setup.py file under the root directory
• 3. Creates a resources.ini under the root directory / .egg-info directory
• 4. Creates a directory locale/LOCALENAME/ under the root directory / .egg-info directory
• 5. Copies the .po file to the directory created in step 4
• 6. Converts the .po file to a machine readable .mo file
• 7. If specified copies an images directory under the directory created in step 4
• 8. If specified copies an html directory under the directory created in step 4
• 9. Registers the .mo file with the resources.ini
• 10. If specified registers the images directory with the resources.ini
• 11. If specified registers the html directory with the resources.ini
• 12. Activates the egg in develop mode for testing

Chandler Egg Creation

The first step is to extract the Chandler.pot file using createPot, then copy or rename that file from Chandler.pot file to Chandler.po, open the Chandler.po file in a po editor such as poEdit and localize the content.

Tip: You should save the pot file somewhere and archive it with an unambiguous name, using the svn number for instance, e.g. Chandler11713.pot or the date if you're not very familiar with svn, e.g. Chandler20060907.pot. Next time you want to localize a newer version of the program, you'll then be able to compare the new pot file with the old and see what changed and how much work you have to do. For the moment, createPot and createTranslationEgg do not handle differences between versions so this tip will save you time in the future.

Hint: Chandler is still rather nimble in term of User Interface so the translation process is quite short. I was able to translate Chandler in French in 8 hours, including writing this documentation.

To build a translation egg for the French Locale ('fr') type the following:

./tools/createTranslationEgg.py -c -l fr

This will create an egg Chandler.fr in the current working directory. Note that the Chandler.po file must be present in either the current working directory or $CHANDLERHOME. If the file is in an alternate location, add the additional argument -f PATHTOCHANDLERPOFILE/Chandler.po

If you wish to have the egg created in an alternate directory, pass the -d PATHTODIRECTORY argument.

At this point the egg has already been created and installed in develop mode and all that is needed is to start Chandler with the -l fr command to see the localization:

./release/RunChandler -l fr

Tip: You do not have to wait to have a complete Chandler.po to start creating a translation egg and launch Chandler to look at your work so far. The egg creation is extremely fast and launching Chandler under the command line is not an problem.

Tip: Chandler does save some user interface strings in its repository. If you relaunch Chandler on a new egg you might be surprised not to see your translation showing up. To force a repository clean up you can depress the Control key when launching Chandler and select the "start from scratch" option. Alternatively, you can add --create in the command line:

./release/RunChandler --create -l fr

There are two additional optional arguments that can be passed the --imagedir and --htmldir. The arguments must point to a valid directory on the file system. The tool will copy the files / sub-directories under the directory to the egg and register the resources with the resources.ini.

So to localize the splash screen image splash.png one would create an alternate image also named splash.png place it in a folder and pass the --imagedir argument to the tool. This result in the Splash screen using the new image instead of the Chandler default image the next time Chandler is started in the given locale:

./tools/createTranslationEgg.py -c -l fr --imagedir ./images_fr -d ./myoutputdir

Chandler Examples Egg Creation

Creating a localized Chandler Examples egg is basically the same as creating a Chandler egg. The -l locale argument is still required and the optional arguments --imagedir, --htmldir, and -d can be used.

The only differences are, the name of the po file should be ChandlerExamples.po and the name of the localized egg will be Chandler-ExamplesPlugin.LOCALNAME.

To build a translation egg for the French Locale ('fr') type the following:

./tools/createTranslationEgg.py -e -l fr

This will create an egg Chandler-ExamplesPlugin.fr in the current working directory. Note that the ChandlerExamples.po file must be present in the either the current working directory or $CHANDLERHOME. If the file is in an alternate location add the additional argument -f PATHTOCHANDLERPOFILE/ChandlerExamples.po

3rd Party Egg Creation

Again, creating a localized 3rd party egg is basically the same as creating a Chandler egg. The -l locale argument is still required and the optional arguments --imagedir, --htmldir, and -d can be used.

The only differences are instead of passing a -c or -e one passes a -p PROJECTNAME and the path the the .po file must be explicitly specified via the -f argument.

So to build a MyParcel egg translation for the French locale:

./tools/createTranslationEgg.py -p MyParcel -f ./MyParcel.po -l fr

This will create a MyParcel.fr translation egg in the current working directory that has already been activated in develop mode.

Discussions

• Chandler-dev: Simple guide to localizing Chandler
• Chandler-dev: Chandler in French and in Finnish!

Existing translations

• A tentative translation egg file Chandler.fi_FI-1.0-py2.4.egg for Finnish language.

-- PhilippeBossut - 08 Sep 2006