CPS Translation HOWTO

Authors: Stefane Fermigier
Marc-Aurèle Darche
Revision: $Id$


This document gives some background information and tips on translating CPS .po files.


Each CPS product has an i18n directory containing all pot/po files plus some others. All of them should be translated.

1   Definitions

PO file (.po file): PO stands for "Portable Object". PO files contain sets of strings which associate each translatable string with its translation in a particular language. A single PO file relates to only one language. A PO file is derived from a POT file and is edited either by hand or using KBabel.

POT file (.pot file): POT stands for "Portable Object Template". A POT file is built by extracting all the translatable strings from application source files. A POT file does not contain translations into any particular language. It is used by the translators as a template.

Message ID: msgid is the keyword which introduces the original string in a PO file. It is followed by a C-like string that spans one or more lines.

Message String: msgstr is the keyword which introduces the translated string in PO file. It is followed by C-like string that spans on one or multiple lines.

Fuzzy translation: This is a flag generated, in general, by msgmerge. It shows that a msgstr string might not be a correct translation. The translator must see and make modifications to the string if necessary and then remove the "fuzzy" flag from the message's comment.


2   Files

3   Adding a new translation to CPS

Use the Codes for the Representation of Names of Languages http://www.loc.gov/standards/iso639-2/php/code_list.php to determine which language code to use for naming your files.

To start your translation, make a copy of the master pot file. (This copy must be named according to i18n rules: en.po or en_US.po and not EN.po, en_us.po or en-US.po. Case and underscore are important.)

Next, add your language in CPSDefault's custom.pot file. There's a Languages paragraph and the msgid will be like label_language_en_US.

Then add your language to the language vocabulary defined in CPSDocument/skins/cps_document/getDocumentVocabularies.py if you use CPS < 3.4. For CPS >= 3.4, do the same in ''CPSDefault/profiles/default/vocabularies/language_voc.xml''. There are three keys to add: the first one is the i18n label, the same that you used to name your po file; the second one is how you name your language in your own language -- note how some strings are not to be translated; the third one is the msgid you used in CPSDefault's custom.pot file, it will be used when the vocabulary gets translated.

If you use CPS < 3.4, you will also need to modify the file CPSDefault/zmi/manage_addCPSSiteForm.dtml. If you use CPS >= 3.4, then do the same in CPSDefault/factory.py. There's a Languages box which contains a list of two element tuples. Add a new tuple for your language. The first element will be the i18n label and the second your language name in English.

Now you can start translating message strings. You should use dedicated tools and should not handle it by hand so you will avoid most common mistakes.

3.1   How to have CPS reread the translation files

3.1.1   For CPS 3.4 and subsequent versions

Updating the translations from the translation files can be done through the portal_setup tool (located at the root of your CPS instance in the ZMI) by importing the needed steps from the Import tab, but before that you need to add your language code to the available_languages property of your CPS site (Property tab of your CPS instance in the ZMI).

If the translations you are doing only affect the CPSDefault, CPSSchemas, CPSDocument, CPSDirectory, CPSNavigation, CPSPortlets, and CPSSkins products, then you need to import the Localizer step from the CPS Default Site profile:

portal_setup -> Import -> Select Localizer -> Select CPS Default Site -> Import selected steps

If the translations you are doing also affect other products you will need, just the same, to select the profile for each of these products and import their Localizer step.

Alternatively one can also use the old way (read the next section) but it may not be working anymore anytime.

3.1.2   For CPS prior to CPS 3.4

Updating the translations from the translation files can be done through an external method. Go to the ZMI and select the i18n Updater (located at the root of the CPS instance). Then select the Test tab.

If this external method does not exist you may try to create it with the following parameters:

Id: i18n Updater
Title: i18n Updater
Module Name: CPSDefault.cpsinstall
Function Name: cps_i18n_update

3.1.3   Zope 3 non persistent i18n system

Some CPS producst use the new Zope 3 non persistent i18n system. That is the case of the CPSSharedCalendar product.

For products using the Zope 3 non persistent i18n system, messages are located in Products/PRODUCT_NAME/locales/. After editing the po files you should compile them as follows

$ msgfmt -o file.mo file.po

Thus for CPSSharedCalendar, edit the files in Products/CPSSharedCalendar/locales and then after editing the po files compile them as follows

$ msgfmt -o cpscalendar.mo cpscalendar.po

Then you have to restart Zope to see your modifications applied. There is no need to rerun the profiles.

4   How to contribute your translation or translation updates

Open up a ticket in trac https://svn.nuxeo.org/trac/pub/newticket with "i18n" as keyword and your translations bundled in a TAR GZ or ZIP archive as a file attachment.

You can use the account tracguest/tracguest if you haven't an account already.

5   Software

KBabel runs under any Unix flavor where KDE is ported, which includes Cygwin for Windows.

Xemacs has a po mode, hard to use, but very useful.

GTranslator: Runs under any Unix flavor where Gnome is ported.

poEdit: Runs under Linux and Windows (http://poedit.sourceforge.net/).

6   Online tools

Automatic translations could be useful to recall a few vocabulary items, if you don't have a dictionary (either paper or online), but do NOT use them for translating a whole sentence: they won't do your job as well as yourself!

Google's language tools: http://www.google.com/language_tools

Babelfish: http://babelfish.altavista.com/babelfish/tr

InterTran translation: http://www.tranexp.com:2000/Translate/result.shtml

Grand dictionnaire terminologique (French/English/Latin technical terms): http://granddictionnaire.com/btml/fra/r_motclef/index800_1.asp

Acronym Finder: http://www.acronymfinder.com/

Cambridge Dictionaries online: http://dictionary.cambridge.org/

Dictionary.com: http://www.dictionary.com/

7   Good practices

First, be sure you use the most up-to-date .po files. That is, make sure that you are getting the .po files from the last CPS release source archive or, better, that you are using them from a fresh SVN checkout http://svn.nuxeo.org/trac/pub/browser/ . The rationale is that the files on which you are working have certainly been modified (and sometimes fixed) since they have been released or that you have downloaded them, even if you are an official translator for a given language. This is because we use an automatic updater on all .po files.

Never add a string outside custom.pot files. It would break our updater, and consequently delay the addition of your po files. For the same reason, do not use Localizer to export your files.

Look at the context. The best way is to check where msgids appear in the site, then look at the msgid context in the product (po files and skins). If you have doubts, you can, in this order, check en.po, check another po file that you understand, then ask the CPS translators list <cps-translators@lists.nuxeo.com>.

Once your translation is done and uploaded into CPS, test it against non-technical people, which are the common audience for CPS. This is necessary to make sure you don't use terms that are too technical or too abstract.

If you are in doubt about another translation you are using for inspiration, ask the mailing list so you can contact the upstream translator or people speaking that language.

8   General rules

Action names or page title:

Form actions (buttons):


If you want to add or fix something in this document, please join the list of CPS translators <cps-translators@lists.nuxeo.com>.

9   Translation coverage

The translation coverage for CPS 3.3.8 and the current developments (trunk) are respectively http://www.cps-project.org/static/i18n/CPS-3.3.8/i18n_coverage.png , http://www.cps-project.org/static/i18n/CPS-trunk/i18n_coverage.png

If you want to produce those graphs yourself you need to use the i18n_coverage script from the CPSI18n product and the gdchart python program (on Debian Sarge apt-get install python-gdchart libgdchart-gd1-noxpm).

And here is a possible command line:

$ CPSI18n/bin/i18n_coverage -v --dir
/usr/local/zope/instance/cps-zope2.9/Products CPS* Cal* -eCPSSkins