Active Localization Projects
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:
svn checkout svn+ssh://svn.osafoundation.org/svn/localizations/chandler/trunk/ localizations
Now you are ready to start localizing
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
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 firstname.lastname@example.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.
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
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
will be created in the current working directory. If you wish to have the egg created in an alternate directory, pass the
Now that the egg is created and installed in develop mode, all that is needed is to start Chandler with the locale
argument to see the localization:
> cd $CHANDLERHOME
> ./release/RunPython Chandler.py -l fr
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
. 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.
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 email@example.com
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
in the current working directory. If you wish to have the egg created in an alternate directory, pass the
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
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"
"Start up error.\n"
"Here are the bottom %(numOf)s frames of the stack: %(stacktrace)s\n"
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"
"Start up error.\n" "Here are the bottom %(numOf)s frames of the stack: %(stacktrace)s\n""\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
"Start up error.\n"
"Here are the bottom %(numOf)s frames of the stack: %(stacktrace)s\n"
msgstr "Här är %(numOf)s frames från botten av stacken: %(stacktrace)\n"
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.
the createPot.py script requires the
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
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
- 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:
- Mnemonics are case-insensitive (i.e. both
Bu&bble would be activated by pressing the "B" key), and should be unique for all the items in a menu.
- Accelerators should be unique across the application.
- Accelerators consist of zero or more modifiers (
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!
- 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
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
&Stopper la publication
S&topper la publication
in the .po file.