NLC:New Translators Start here

From Apache OpenOffice Wiki
Revision as of 10:49, 19 January 2007 by Timarandras (Talk | contribs)

Jump to: navigation, search

New translations start here

Working together with I10n Team I10n provides localized builds for many languages.

For translation teams, with every new milestone (version of code) we provide a tarball (file ending in .tar), which contains:

  • a collection of POT files (gettext translation templates, text files ending in .pot)
  • one English (en-US) sdf template file ( format string file, text file ending in .sdf)

From translation teams, we need:

  • your translation file, a .sdf file containing all the English strings translated into your language (or at least 80% translated)

Structure of the .sdf file

A localized .sdf file contains two lines for every translatable string, the first line in English and the second line in your language. The completed translation file is over 20 MB in size, so you should compress it (with bzip), upload it to your http or ftp server, and provide the link to it, so we can download it to build it into the application. Because the build system downloads files automatically, the package name must also follow a specified format. Your filename should look like: GSI_xx.sdf.bz2, where xx is your language code. For example, the Estonian .sdf translation file will have the filename: GSI_et.sdf.bz2.

Using translation memory

If you have translated other software, especially software which performs tasks similar to those of an component (e.g. Gnumeric, AbiWord, Koffice, the GIMP), we recommend you use translation memory, to avoid duplication of work, and to use existing resources as effectively as possible. You can create, maintain and apply your translation memory (TM) using 'plain' gettext (please refer to the gettext manual), and of course, using GUI applications like KBabel, which has a much greater capacity for generating and using translation databases. (GTranslator does not currently handle the wrapped lines in Help.) See the Editors appendix to this document.

Starting from the beginning

This is the basic translation process.

Create a separate directory on your disk, e.g. OpenOffice.

Get the translation files

Download (POT directory) the latest tarball of .pot files and decompress it into your directory.

Get the toolkit

Download the latest version of the Translate Toolkit and install it, using the install script (run install --home=/chosen/directory). The Translate Toolkit depends on the python and python-devel packages, so you must also have these installed on your system.

If you have any problems at all with the Translate Toolkit, please come and ask for some advice on the mailing list, or on the IRC channel on the Freenode network.

Create or update the PO files

Use the pot2po script from the Translate Toolkit. Make it executable as needed. You can edit this script to set the following options.

To apply your gettext translation memory compendium, add the option --compendium=your_compendium_file to the msgmerge line.

Use line-wrapping only when you are using text-based translation tools, e.g. Emacs or vim. Otherwise, you should avoid line-wrapping, it makes Help strings very difficult to read, as it breaks lines inside tags. So replace -w 200 with --no-wrap.

As later versions of the Translate Toolkit no longer merge fuzzy strings by default, there is no longer any need to use the option –no-fuzzy-matching (of course, before removing this, make sure you have the latest version of the Translate Toolkit).

Now we go back to your directory containing the decompressed tarball. It will contain the sub-directory pot and the English .sdf file (en-US.sdf).

(When you download a milestone to replace older translation files, make sure you delete them all (pot directories, en-US.sdf files and any other .sdf files you have created) from this directory (or move them to another directory).)

Run ./pot2po. This creates the sub-directory po, which mirrors the structure of pot.

(When you run this on subsequent milestones, you may see warnings from the script about some .pot files being removed. This means they are probably no longer current. Move any remaining .po files matching those .pot files, to other directories, or change their extension (.po) to something else. When you are sure that the "missing .pot files" aren't caused by a mistake (a missing module in the build, for example), you can simply delete those matching .po files, since they are no longer needed.)

The structure of the pot or po tree is embedded. Files exist inside directories and subdirectories. Do not change this hierarchy in any way.

It is also important to remember that most of the strings are represented by the directory helpcontent2, also called the "Help". You may find it useful to separate this directory from the rest (called the "GUI"), when translating, so your efforts on the interface files do not appear to be a tiny proportion. The interface files are essential, and must be translated first, and maintained at 100% if possible. You can submit this translation separately. Then we all work on the Help, and try and get it done, bit by bit. So don't be discouraged by the size of the tree: it is mostly "Help". :)

Translate the files or update your translation

You are now ready to start translating!

All translations must be in UTF-8 encoding (the standard encoding for translations), so make sure the Preferences in your editor are set to UTF-8.

Your team leader also needs a CVS account, to manage your team's website and documentation files. Instructions on setting up your CVS account, and submitting the JCA copyright assignment, are included in the process of creating your own Native Language project in You do need to use CVS for your website files and documentation hosted on that site, but you can also store files in other source control repositories, e.g., if you don't need them to be on (Some parts of have already moved to SVN.)

When translating, you must preserve the existing structure of each string (placeholders/variables, escape marks, XML tags, etc.). Only change the translatable text.

Look at the string IDs in the .po files: they are mostly quite informative. At least you can understand which type of GUI element is represented by that string (label, menuitem, radiobutton, pushbutton).

There is no need to keep the ~accelerator marks in the translation, as can insert those itself. Accelerators are needed in translation only:

  • for top level menus (File, Edit,...)
  • for general pushbuttons and some other pushbuttons too (didn't find general rule, please fix me)

Due date for translations

Keep an eye on the due date for translation submissions. The release schedule (e.g. 2.2) will be announced on the mailing list.

Check your translation

Always check your translations, running pofilter over your po directory. You can do this at any time, but you must do it, and correct any errors, before submitting your translation. Any errors remaining in the file can break the build, so your language will not be released.

See the pofilter wiki page for instructions.

Convert back to SDF

Once your translation is ready to be submitted, you need to convert it back to .sdf format. Again, the Translate Toolkit comes to our aid, this time with the conversion tool po2oo.

In your main translation directory (OpenOffice, in our example) run this command (or even better, create a script):

export PYTHONPATH=/home/ain/bin/lib/python
/toolkit_dir/po2oo -l xx -t en-US.sdf -i po -o GSI_xx.sdf

Again, xx stands for your language's ISO code (e.g. uk for Ukraine, or zh_HK for Hong Kong Chinese).

Reading this command, you can see that we're telling the command where to find the po2oo process. If you have already set the python location in your PATH, you don't need this part of the command.

So we call po2oo, then we specify our language with -l. Don't forget to input your own language code instead of xx.

Then we tell the process where the template (-t) file is, the file in the original language (usually en-US).

Then we state the input (-i) directory, the po directory, and last of all, we want an output (-o) filename which also contains your language code.

Check the resulting sdf-file with gsicheck. The latest gsicheck can be obtained from

./gsicheck -c -l "" GSI_xx.sdf

Compress and upload the file

Compress the output file eg. with bzip (bzip2 -k GSI_xx.sdf) and upload the file via http or ftp.

Submit the file

To submit your translation file, you include its link in an issue. Go to Issue Tracker. (The link to the Issue Tracker is on the left-hand-side of most webpages.)


  • New issue
  • Component l10n
  • Sub-component code
  • Issue type ENHANCEMENT
  • The version for which you are submitting your translation.

The summary line should describe the type of strings, language and version. For example:

  • [VI] GUI Translation for 2.2 — to submit all the directories except helpcontent2 for Vietnamese
  • [PT_BR] Help translation for 2.2 —to submit only helpcontent2 for Brazilian Portuguese
  • [ZU] GUI and Help Translation for 2.2 — to submit all the directories for Zulu
  • .

The only things which vary about the issue are the version number and the person to whom the issue is assigned. All the issue details will be posted on the mailing list. So keep an eye out for them, and note them down when they appear.

Include the link to your uploaded translation.

You can also briefly describe your translation, e.g. "Here is the initial Xhosa translation for the 2.3 GUI (100%)." or "Here is the updated Catalan translation for 2.4. We have translated all of the GUI and 60% of the Help."

Submit the issue.

What happens after I submit the issue?

Lots of interesting stuff. :)

Once your issue is submitted (even earlier, if you arrange it with Pavel Janik), your translation will be included in the next build. You can download it from the build server (e.g. and start testing it.

You can also see a slideshow about the release process. Note that after 2.2, the release interval will be six months. This allows more time for Quality Assurance (QA).

The release schedule does allow you some time to test your builds and submit language fixes for the translation. It's also important to test how the build works, and to submit issues for any problems.

I need help is large and complex project, so it is particularly difficult for a newcomer. So don't feel discouraged if you become confused, or can't get an overview of the project.

In any case, we are all here to help each other. Please ask on the mailing list, if you have any problems. We will work things out together. :)

Appendix: translation editors

Since a PO file is basically a text file with translation strings, you can edit it in any text editor. However, dedicated PO editors make the process easier, and automate some of the most repetitive tasks.

You could use, for example:

See the list of editors, and comparison chart, in the Tools section of the Localization Guide on the Translate Wiki.

Good luck with your translations. :)

Personal tools