r24 - 12 Jun 2008 - 07:45:56 - GrantBaillieYou are here: OSAF >  Projects Web  >  DevelopmentHome > LocalizationProject

Localization Project



  • BrianKirsch
  • GrantBaillie
  • PhilippeBossut
  • HeikkiToivonen
  • JonasBeckman
  • AndeasBeisemann

Existing translations

  • Chandler.fr-1.0-py2.5.egg: French translation egg
  • Chandler.fi-1.0-py2.5.egg: Finnish translation egg
  • Chandler.sv-1.0-py2.5.egg: Swedish translation egg
  • Chandler.de-1.0-py2.5.egg: German translation egg

Active Localization Projects

12426 jeffrey@osafoundation.org Localization Project: Chinese(??) translation

Localizing Chandler

Getting Started

Note: This documentation assumes that you are able to launch a terminal shell and are somewhat familiar with using the command line interface. However, it is possible to get the .pot file using just your browser and localize it using your favorite tool. You just need the command line to test the localization in Chandler itself. Point your browser to our localizations Subversion repository and download the Chandler.pot for either the trunk (a moving target) or one of the releases.

The first step to localizing Chandler is getting familiar with the terms and concepts leveraged in the application. If you are new to using Chandler, please take a few moments to view the introductory tour. In addition, the complete glossary of Chandler Terminology is available here. If you come across a word or phrase that you are unfamiliar with when translating, the Chandler glossary makes an excellent reference.

Chandlers uses GNU gettext for translations. Instead of having a resource file with ID numbers (Java Resource Bundles), Chandler uses a translation mechanism that maps English strings in the Python code to localized strings specified in a GNU gettext po file. Localizing is the action of creating a po file from a template (pot) and providing a translation for those English strings. For this to work, you first need to get and build the original Chandler source code. See getting Chandler's source code. Once the source is downloaded type "make install" to build Chandler.

The next step is to set the CHANDLERHOME environmental variable to the current working directory that contains the Chandler source. For example, on OS X or Linux (bash shell)

> export CHANDLERHOME=`pwd`

The Chandler project has a separate SVN repository for localizations. This repository contains gettext po translations for Chandler as well as the Chandler.pot template used to create new translations. To check out the localization SVN trunk:

Read-only access:

  • svn checkout http://svn.osafoundation.org/localizations/chandler/trunk/ localizations

Read-Write access:

  • svn checkout svn+ssh://svn.osafoundation.org/svn/localizations/chandler/trunk/ localizations

Now you are ready to start localizing smile

The Chandler localization SVN repository trunk has a directory named template containing the Chandler.pot file.

If this is a new localization, create a directory with the locale name. For example, for the French locale:

> mkdir fr

Now copy and rename the Chandler.pot

> cd fr

> cp ../template/Chandler.pot Chandler-fr.po

Note: Chandler translation files should contain the locale in the file name such as Chandler-es.po (Spanish) or Chandler-fr_CA.po (French Canadian).

If you would like to work on an existing translation, please email grant@osafoundation.org for more details.

Now it is time to localize the po file.

You can either edit the file in your favorite editor such as vi or emacs or use a UI tool specifically designed for localizing po files such as poEdit.

One important piece of information to remember is that Chandler leverages the Python dictionary mechanism for dynamically translated values. Below is a real string taken from a Chandler translation file.

"'%(itemName)s' only appears in '%(collectionName)s'. Removing it will move it to the Trash."

The values %(itemName)s and %(collectionName)s will be replaced at runtime with the the relevant information.

In English this string could evaluate to: "'Lunch on Thursday with Tom' only appear in 'Home'. Removing it will move it to the Trash."

Python dictionary values such as %(itemName)s and %(collectionName)s can be reordered to any position in the translated string as
long as all values are preserved. Not including all dictionary values in the translated string will result in an error at egg build time.

Tip: You do not have to wait to have a complete Chandler translation 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 easy.

The next step is to package and install your translation in Chandler.

The tool used to build and distribute translations is $CHANDLERHOME/tools/createTranslationEgg.py.


The createTranslationEgg script has a number of advanced features that can be viewed by passing the -h (help) argument to it, however building a basic translation egg for install to Chandler is incredibly simple.

To build an egg for, say, the French Locale (fr) type the following in the same directory as the Chandler-fr.po:

$CHANDLERHOME/release/RunPython $CHANDLERHOME/tools/createTranslationEgg.py -c -l fr

The -c argument tells createTranslationEgg to build an egg for Chandler and the -l argument tells which locale the egg provides a translation for.

After running the createTranslationEgg script, an egg named Chandler.fr will be created in the current working directory. If you wish to have the egg created in an alternate directory, pass the -d PATHTODIRECTORY argument.

Now that the egg is created and installed in develop mode, all that is needed is to start Chandler with the locale -l argument to see the localization:


> ./release/RunPython Chandler.py -l fr

Note: Each time a change or addition is made to the po file, the egg must be rebuilt and Chandler restarted for the change to be seen. In addition, Chandler ships with pre-populated user data such as the Incoming and Outgoing Accounts, the Home, Work, and Fun Collections and the Welcome note. Theses values are editable by the user and thus will no longer localize when changed. For example, if a space or other character is added to the body of the Welcome Note in the Detail View that value now becomes user data and will no longer use the Chandler translation mechanism. If you find that changes in the po file are not getting reflected in one or more of the user data values this may be the issue. In this case simply start Chandler with the additional -c flag to recreate your Repository and reset the pre-populated user data. ie. ./release/RunPython Chandler.py -c -l fr. Any personal data will get deleted when recreating the Repository. Another option is to use the -P argument to specify a different directory for your Chandler profile to use with localization testing. With the -P argument Chandler will access or create a new repository in the directory specified ./release/RunPython Chandler.py -l fr -P PATHTODIRECTORY. By leveraging the -P option your personal profile and Repository will remain untouched.

Once your translation is complete and verified in the Chandler UI, it is time to check the translation in so it can be incorporated in the Chandler build process.

Note: Starting with 0.7.3, Chandler will package translations in its releases. There is a new menu under the "File" menu named "Switch Language ...". Selecting this menu, launches a dialog that allows the user to select from any of the localizations shipped with Chandler.

If you have commit rights to the localization SVN repository (and assuming a French translation), in the fr directory containing the Chandler-fr.po file type:

> svn commit -m "ADD YOUR COMMIT MESSAGE HERE" Chandler-fr.po

If you do not have commit rights please mail the completed and verified translation po file to grant@osafoundation.org for incorporation in to the Chandler build process. You will also need to fill out a Contributor License Agreement before the Chandler Team can accept your localization submission.

If you would like to become a commiter to the Chandler localization repository, the process for gaining commit status is documented here.

Should you want to create a downloadable egg for your own distribution simply type:

> $CHANDLERHOME/release/RunPython $CHANDLERHOME/tools/createTranslationEgg.py -c -l fr --dist

This will create a distribution egg (assuming Python 2.5) named Chandler.fr-1.0-py2.5.egg in the current working directory. If you wish to have the egg created in an alternate directory, pass the -d PATHTODIRECTORY argument.

Installing Language Eggs

To install the distribution type:

> $CHANDLERHOME/release/RunPython -m easy_install Chandler.fr-1.0-py2.5.egg

On Ubuntu Feisty Fawn, Gutsy Gibbon or Mac OS X "Leopard" to install the distribution type:

> $CHANDLERHOME/release/RunPython -m easy_install -x --install-dir=$CHANDLERHOME/release/site-packages Chandler.fr-1.0-py2.5.egg

Merging Translations

With each new Chandler release, the OSAF localization team will merge the previous Chandler po files with the new Chandler.pot. Localizers will then svn update and add translations for any new strings introduced in the Chandler release. As a general rule, it is OSAF's policy not to alter existing English Python strings from release to release. This makes the localizers job much easier. However, on the rare occasion an existing English string will need to be modified. When this happens the altered entries will be marked as "fuzzy". The term "fuzzy" comes from the GNU gettext API and implies that the current localization and the English string it was derived from are no longer an exact match. In the po file this will be presented as:

# #: Chandler.py:159
#, fuzzy, python-format
#| msgid "Here are the bottom %(frames)s frames of the stack:n"
msgid ""
"Start up error.n"
"Here are the bottom %(numOf)s frames of the stack: %(stacktrace)sn"
msgstr "Här är %(frames)s frames från botten av stacken:n"

The #| msgid line will contain the previous English key for comparison. Notice in the above example that the English string has changed from "Here are the bottom %(frames)s frames of the stack:n" to "Start up error.n" "Here are the bottom %(numOf)s frames of the stack: %(stacktrace)sn""n"

Should you wish to perform your own merge you can either install the msgmerge tool which is part of the GNU gettext library or use poEdit.

Using the msgmerge tool and again assuming a French translation:

>  msgmerge --previous --no-wrap --backup=numbered --update Chandler-fr.po ../template/Chandler.pot

Running the tool will update the Chandler-fr.po file with the changes in the Chandler.pot and save a numbered backup of the original Chandler-fr.po file starting with "Chandler-fr.po.~1~".

The msgmerge tool tends to try to hard to match translated strings in the po file with the updated Chandler.pot. What this means is that the po will contain a number of fuzzy entries pre-filled in with localizations. Simply open the file and search for all the fuzzy entries and confirm by looking at the #| msgid original English string that the translation is correct. In most cases, the msgid and msgstr will be a close match that requires minimal changes.

If you wish to merge using poEdit. The application has a menu item under "Catalog" named "Update from POT file...". Selecting this menu item opens a file dialog. Simply point to the new Chandler.pot in the SVN localizations template directory and poEdit will merge it with the current po file.

Just as with the msgmerge tool, you will need to find all "fuzzy" entries and confirm that the correct localized string is being used.

Once you have reviewed a fuzzy entry and finished localizing the string the "#, fuzzy" and "#| msgid" tokens should be removed from the comments for clarity. Using our previous example, the finished translation would be:

# #: Chandler.py:159
#, python-format
msgid ""
"Start up error.n"
"Here are the bottom %(numOf)s frames of the stack: %(stacktrace)sn"
msgstr "Här är %(numOf)s frames från botten av stacken: %(stacktrace)n"

Note: The translated German string is not 100% correct, but is used to illustrate the point. In the future when a German translation of Chandler is complete the example will be updated.

Advanced Localization Features

Generating the Chandler.pot

Before a Chandler release, an updated Chandler.pot file generated from the release SVN branch will be in the template directory and the localized po files merged and ready for translation additions.

Should you wish to generate your own Chandler.pot from the SVN Chandler trunk the createPot.py script is used to accomplish this.

Note: the createPot.py script requires the xgettext utility which is installed as part of the GNU gettext library.

Running the createPot.py will generate a Chandler.pot in the current working directory:

> $CHANDLERHOME/release/RunPython $CHANDLERHOME/tools/createPot.py -c

WARNING: generating and localizing from the SVN Chandler trunk Chandler.pot is at your own risk. It will be your responsibility to rectify any string changes, additions, and removals with the release branch. A translation po file whose msgid strings do not match the SVN release branch Chandler.pot template will not be accepted and included in the release.

Menu mnemonics and accelerators

To get the terminology straight here:

  • Mnemonics are used on Windows/Linux to navigate by keyboard when a given menu has focus. To specify a shortcut, put a & before the shortcut character in the menu item's title. So, in English, the top-level "File" menu item has a title of &File, is displayed as File, and can be activated by pressing Alt+f.

  • Accelerators are key combinations used on all platforms to activate menu items (even when not visible). An example accelerator is Ctrl+C, which activates the Edit >> Copy menu item.

Here are some guidelines:

  1. Mnemonics are case-insensitive (i.e. both &Bubble and Bu&bble would be activated by pressing the "B" key), and should be unique for all the items in a menu.
  2. Accelerators should be unique across the application.
  3. Accelerators consist of zero or more modifiers (Shift, Ctrl, Alt) separated by plus signs and followed by a capital letter or special key (like the function key F11). It is usually best not to translate accelerators, unless it is standard for applications in your language. If you do decide to translate an accelerator, don't translate the modifiers!
  4. If you're a Mac user, note that the modifier Ctrl is special: It is mapped to the "Command" (or "Open Apple") modifier on the Mac, and "Control" on Linux/Windows.

In practice, mnemonics are a challenge for translation, because it's impossible to tell from the .po file where in the menu hierarchy your translated title will appear. This makes it difficult to know which mnemonics need to be unique in 1. above. To help somewhat, there is a test script in the chandler subversion repository that flags cases where the above guidelines are not followed. To run it, run the following script from a subversion checkout of Chandler, with your translation egg installed as above:

$CHANDLERHOME/release/RunPython $CHANDLERHOME/application/tests/TestMenus.py --locale fr

(substitute your locale for fr above, of course). This will either show success, or report problems, like:

Collision for mnemonic 's':
---Mnemonics used in this menu: <cdgimnprsvy>---
   Barre de navigation >> &Supprimer;
   Barre de navigation >> &S;'abonner...
   Barre de navigation >> &Stopper; la publication

So, the above example is showing that the mnemonic 's' is being used in 3 places in the "Barre de navigation" menu. The "--Mnemonics used in this menu: ... " line, is to help you to decide what mnemonics are still available. So, one way to fix the mnemonics would be to change

&S'abonner to S'&abonner, and &Stopper la publication to S&topper la publication in the .po file.

Happy Translating!

toggleopenShow attachmentstogglecloseHide attachments
Topic attachments
I Attachment Action Size Date Who Comment
elseegg Chandler.fi-1.0-py2.5.egg manage 76.6 K 28 Nov 2007 - 13:58 BrianKirsch Finnish Translation
elseegg Chandler.fr-1.0-py2.5.egg manage 35.4 K 28 Nov 2007 - 14:05 BrianKirsch Updated French Translation
elseegg Chandler.sv-1.0-py2.5.egg manage 74.7 K 28 Nov 2007 - 15:45 BrianKirsch Swedish Translation
elseegg Chandler.de-1.0-py2.5.egg manage 76.5 K 31 Dec 2007 - 11:59 BrianKirsch German Translation
View topic | Edit |  | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r26 < r25 < r24 < r23 < r22 | More topic actions...
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.