Working on translations

There is actually two separate translation infrastructure in the PLM. The first one is intended to allow the translations of mission texts while the second translates the interface itself (menu, buttons and such). This page describes both (at least it will soon -- only the first it there for now).

Translating the missions

To translate the exercises and lessons, we use po4a project (PO for anything), which was designed to ease the maintainance of documentation translations.

TL;DR: Quick guide

• Install po4a (how?)
• Run po4a po4a.conf from the main directory (to extract the things to translate)
• Edit the file l10n/missions/<yourlang>.po
• Run po4a po4a.conf from the main directory (to reinject the translations into master documents)
• Commit your po file and the html files (preferably separately). Avoid committing the other po files.
• Open a pull request.

Installing po4a

The first thing to do is thus to get that software and install it. It's realy trivial on debian and ubuntu boxes:

sudo apt-get install po4a

It should be quite simple on other linux flavors, too. Installing the beast on Windows or OSX is more adventurous, and there is no ready to use path for this. We wrote a quick and dirty installation guide for OSX. If you manage to get a nice way to do it, please document it in this wiki. As we know quite well the po4a guys, we could also get changes integrated if needed.

Translation workflow

Here is the big picture from the po4a documentation:

  Input document --\                          /---> Output document (translated)
                    \                        /       
                     +-->--   po4a  --------+
                    /                        \
  Input PO --------/                          \---> Output PO (extracted)

That is to say that all html files written manually should be in english. If you want to fix a translation, do not fix the html file directly or your changes will get lost since they are generated files. Instead, modify the lib/l10n/.po file to fix the problem, and rerun po4a. These po files are at the same time input and outpout in the process: the new english parts are added to the file, and old translations get "fuzzied" while the translation parts are used to generate the translated html files.

It may sound a bit strange at the first glance, but it's quite simple at the end. Check the po4a documentation, it's quite complete.

How should I edit that po file?

I personally use emacs for that, but others tools are listed on the Gettext and the Computer-assisted translation wikipedia articles.

Adding a new file to translate

Simply add a line in the po4a.conf file at the root of the JLM project. The syntax should be quite self-explanatory, but the po4a documentation is there for you if you don't feel so.

Starting the translation to a new language

Simply add your ISO language code in the first lines of the po4a.conf file, and relaunch po4a. Good luck! The PLM includes a very large amount of text, but your work is definitely useful. Teaching programming to peoples is the most useful thing you could do on earth. Well, at least, that's an important one ;)