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

• Clone the git repository on your machine.
• Install po4a (how?)
• On need, add your language to po4a (how?)
• Run po4a po4a.conf from the main directory, to extract the things to translate (what do you mean?).
• Edit the file l10n/missions/<yourlang>.po (with which editor?)
• (if you find a typo, fix it or report it -- how?).
• Run po4a po4a.conf from the main directory, to reinject the translations into master documents. (hu?).
• Commit your po file and the html files (preferably separately). Please avoid committing the other po files from other languages as your changes may interact badly with the work of your fellow translators in other languages.
• Open github pull requests when you have some progress to send. Don't wait for the full completion of your translation to share it, but send it every once in a while. That way, if real life prevents you from completing the translation, your work will not get lost.

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.

I found a typo!

As a translator, you will probably find some typos or unclear sentences in the english text. We need to hear from it to fix it! Simply note that each time we improve the english text, every translations have to be updated to reflect it. As a result, the kind of changes that we prefer are either fixing little typos (it must be done), or bold sentences rewriting.

Marginally improving the text to make it less bad is marginally helping us: it's still not good for the student, and it put an extra burden on your fellow translators for other languages. Don't make it less bad, make it good! Even if you have to change the text a lot for that!

In practice, directly change the html file containing the english text. Do not edit the plm.pot file, or your changes will be overwritten by the next run of po4a.

If you don't want to do the change yourself, or if you are not sure of what the correct fix would be, just open a new issue on the bug tracker, and we'll fix it for you.

Adding a new file to translate

Simply add a line in the po4a.conf file at the root of the PLM 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 ;)