Working on translations

The PLM entails several categories of text that need to be translated. You can first translate the mission texts, you can translate the web interface and you can translate the builtins (such as forward() for buggles). This page describes how to do this.

If you really want, you can also translate the interface of the old (deprecated) Java application itself, but that's not really advised at this point.

Web Interface's Translation Quick Guide

Note that this interface is not in the PLM repository, but in the webPLM project.

To translate the interface, we use angular-gettext. You can find all its documentation on the website but here is a quick guide for translators:

• Fork and clone the webPLM git repository on your machine.
• In the repository, enter the command npm install .
• On need, add your language to the webPLM interface (how?).
• Edit the file po/<yourlang>.po (with which editor?).
• (If you find a typo, fix it (in the HTML/JS source files, NOT in the msgid of the po file) or report it -- how?).
• Run grunt gettext-update from the main directory so that your work is integrated to webPLM.
• Test your translations in the interface.
• Commit your po file.
• 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. "Release soon, Release often" is one of the most important saying in the open source world.

Missions' Translation Quick Guide

We use the po4a project (PO for anything) to translate the missions and lessons. The same texts are used for both the Java interface and the Web interface. Here is a TL;DR guide:

• Fork and 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 (in the HTML source files, NOT in the msgid of the po file) 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. "Release soon, Release often", you know the story.

Builtin's Translation Quick Guide

You can also translate the universes' builtins. For example, it is easier for French pupils to call the avance() function than the forward() one. This part is not automated at all, and you should edit the Java/Scala/Python files directly. Search for the string BINDINGS TRANSLATION in the source code, and do something similar to what's done for French.

Java Interface's Translation Quick Guide

This is the old interface of PLM, and not much work is planned on this code. You should probably not translate this but only the web interface (see above).

If you really want, we use standard gettext for the interface:

• Fork and clone the git repository on your machine
• On need, add your language to the PLM interface (how?).
• Edit the file l10n/engine/<yourlang>.po (with which editor?).
• (if you find a typo, fix it (in the Java/Scala source files, NOT in the msgid of the po file) or report it -- how?).
• Run ant i18n-update from the main directory so that the PLM finds your work.
• Test your translations in the interface.
• Commit your po file.
• 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. "Release soon, Release often" is one of the most important saying in the open source world.

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.

If you edit directly the file, you should only edit the msgstr strings. NEVER edit the msgids, or your changes will be lost when the file gets updated.

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 you 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, but not fiddling around.

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 nor the msgids of your po file, or your changes will be overwritten by the next material extraction (with po4a for the missions, gettext for the java interface, or angular-gettext for the web interface).

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.

Translating the Web interface to a new language

• Add the language in /conf/application.conf file as indicated here.
• Initialize the new catalog using by copying the file /po/template.pot to /po/<yourlang>.po

The PLM interface contains quite a lot of strings, but much less than the pedagogical content, which is much longer to fully translate. So translating the interface is a good starting task.

Translating the Java interface to a new language

Please remember that the future evolutions of the Java interface remain uncertain. You should consider translating the Web interface instead.

To start a new translation of the Java interface anyway, you want to add your language to the humanLangs variable in file src/plm/core/model/Game.java. You should add something similar to the existing ones, such as {"Francais","fr"}. The first string is the displayed name while the second one is the short name, used in the little menu in the interface, but also in the files' name extension. You should use the ISO code of your language as short description.

Then, you can copy the l10n/engine/plm.pot into l10n/engine/<yourlang>.po. There is two fields that you should update in the header of this file:

• Charset (in Content-Type: text/plain; charset=). If you have no clue, then UTF-8 is probably the right value.
• Plural-form:. Check this page to find out the right value to your own language.

Translating the missions 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 mission include 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 ;)

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.

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.