[Chandler-dev] Simple guide to localizing Chandler

[Brian Kirsch]

Hi Philippe,
Here are some instructions on how to localize Chandler.

There is an open task for Markku bug: 6657 to create more structured HOW 
TO documentation.

There are two tools:
1. $CHANDLERHOME/tools/createPot.py
2. $CHANDLERHOME/tools/createTranslationEgg.py

createPot Tool
---------------------------
This tool parses Python source code and wx XRC files for localizable 
strings. The tool 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 the tool the $CHANDLERHOME environmental variable must be set or 
the tool must be run from the $CHANDLERHOME directory. If the the 
$CHANDLERHOME environmental variable is set the tool can be run from any 
current working directory.


Chandler Localization:
====================
To grab all localizable strings for Chandler run the tool with the -c 
flag ie. ./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 the tool 
with the -e flag ie. ./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 the tool has two command line arguments:

  -pPROJECT, --project=PROJECT
                        Extract localization strings Python and XRC 
files for
                        the given project. A gettext .pot template file
                        "PROJECTNAME.pot" is written to the current working
                        directory.
  -dDIRECTORY, --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 the tool 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 Tool
--------------------------------------
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 the createPot tool defaults are 
provided for working with Chandler and the Chandler Example egg parcels.

The tool 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. Coverts 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 copy or rename the Chandler.pot file to Chandler.po 
then open the Chandler.po file in your favorite po editor such as poEdit 
and localize the content.

To build a translation egg for the French Locale ('fr') type the 
following ./tools/createEggTranslation.py -c -l fr. The will create an 
egg "Chandler.fr" in the current working directory. Note that the 
Chandler.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/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.

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/createEggTranslation.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/createEggTranslation.py -e -l fr. The will create an 
egg "Chandler-ExamplesPluin.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/createEggTranslation.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.




Have fun!
-Brian















-- 
Brian Kirsch 
Internationalization Architect / Mail Service Engineer
Open Source Applications Foundation
543 Howard Street 5th Floor
San Francisco, CA 94105
http://www.osafoundation.org