CPS and i18n

Author: Stefane Fermigier
Revision: $Id$


This documents gives rules and hints for translating CPS 3 and third-party products.


1   Tools Used

We use a combination of "TranslationService":http://www.zope.org/Members/efge/TranslationService and "Localizer":http://www.j-david.net/software/localizer. These products are shipped with CPS.

The CPSI18n product provides you with two tools : make_pot and update_pos to help with managing the pot/po files. (See the related section below.)

Messages are stored in a MessageCatalog object inside the Localizer instance. Hence, the translation_service object holds paths to MessageCatalog objects like "Localizer/default".

We use only the Default domain for CPSDefault and all the required products, this means that we will have only one MessageCatalog.

CPSDefault skins does not provide a 'i18n:domain' attribute or at least the "default".

For the python script file we have to use this syntax:

cpsmcat = context.translation_service

Please see if there is any howto-l10n-xx.txt to guide you in the xx translation.

2   Guide to Prefixes Your msgid (mostly from plone i18n guideline)

msgid is a short name like the one you would use for a variable.

We added certain standard prefixes for IDs so you can understand where they are used (semantic differences are easier to spot this way), and easily locate them. When sorted, the IDs will be grouped by type automatically. Here are the standard prefixes:

There are also Product-specific prefixes, e.g. the Product ZWiki has a heading, then the prefix would be |zwiki_heading_edit_wiki_page|. This prevents collision between Message IDs.

3   How to Translate

4   Rules to Generate pot/pos Files and Updating Them

Included in the CPSI18n product you'll find 2 tools automatizing the msgids gathering and updating:

  1. make_pot: Initialization (see the scenario below).
  2. update_pos: If your ZPT's change or you want to add some msgids.

Check the doc of CPSI18n in order to make these tools work.

The idea is to parse the ZPTs directly, extracting the content of the i18n tags and generating the pot/po files for a product.

This process basically uses: GNU Gettext, OpenTAL, pax (XML parser). You'll need GNU Gettext version >= 0.11.4-7 installed on the computer where you will launch the scripts make_pot and update_pos.

Set ISO 8859-15 encoding in your po editor (Whatever the tool) !! The characters with accents will not be accepted at diplay page time if you don't. ;)

update_pos and make_pot can handle a blacklist pot file, removing all msgid that are present in then blacklist pot file, this is usefull when you share a mcat with another products and you don't want to duplicate existing translation.

To use this feature you need to edit/create a file named .blacklist_pot in i18n repository and set the content to the path of the pot file like '../../CPSDefault/i18n/cpsdefault.pot', by doing this the update_pos command will remove all msgid found in your template and custom that exist in the ../../CPSDefault/i18n/cpsdefault.pot file.

5   Process Outline

Before starting create a subdirectory i18n within your product directory.

5.1   Main Branch (init)


$ cd ./i18n

Use make_pot the first time when you wanna start the internationalization of your product. You'll get all the necessarily files. Simply:

$ make_pot
Translate the local files using Kbabel
Localizer feeds the po files

5.2   Branch 1

You change your ZPTs


$ update_pos
Translate the local files using Kbabel
Localizer feeds the po files

5.3   Branch 2

You add some msgids in the custom.pot file. (Typically for the dynamic content.) You can check the localizer catalog after asking CPS to interpret them. Just if you'd like to be sure to have all of them. BUT DON'T USE Localizer FOR EXPORT ANYMORE !!
Translate the local files using Kbabel do not change
Localizer feeds the po files


  • make_pot and update_pos will parse all your zpts in the skins folder make sure that your zpts are working and that there are no extra zpt before running those commands.
  • When using emacs or other po editor do not change msgid orders or comments to make cvs diff usefull.

5.4   DEBUG mode with make_pot

You might find useful the debug mode of make_pot if your ZPTs contained errors. It means if you didn't set the i18n tags properly.

It will be use if you get some errors with make_pot.

make_pot can feed one directory or one single file:

make_pot <file|directory>

It will check all the ZPTs within directory and will inform you which one are not well formed (By mean of i18n tags).

6   Within CPS3