TranslatingActivities

From WorldWideWorkshop-OLPC wiki

Setting up the environment

First things first

In order to add and edit translation files in the XO bundles for the MaMaMedia activities, a number of tools are needed. The easiest setup is having a standard linux distribution and using the sugar-jhbuild environment. Installation of the linux OS is out of the scope of this document. Instructions on installing the Sugar environment can be found at http://wiki.laptop.org/go/Sugar_with_sugar-jhbuild.

I never tried, and if I can get away with it never will try to install sugar-jhbuild on windows, but there are alternatives we can use in windows. One such alternative is using the standard zip file support found in windows XP and the open source translation handling tool poEdit. This is the method explained below for the windows platform.

Although these guidelines apply to any activity, the examples will be given using the Slider Puzzle.

Know your files

Since we don't yet have a source versioning control system in place the full source code for activities is inside the distribution bundles. This has a few important drawbacks and as such a better solution is being implemented, but for now great care must be taken to make sure the core developer(s) of the particular activity you are tweaking get the changes you make.

 We now have version control, and if at all possible one should use the sources for any change needed,
 posting it as either a patch sent to the main developer by mail or by directly merging into the repository.
 This, however, assumes a moderate level on technical capacity, so it should be discussed somewhere else.

Choose a place, any place, inside your harddrive to work. Just make sure you remember the place you choose. Unzip the bundle into that place and you'll get a directory, in our case called SliderPuzzle.activity, holding a bunch of files and a few directories. The ones we care about right now are:

 SliderPuzzle.activity
  + locale
  |  + pt
  |     + LC_MESSAGES
  |        + org.worldwideworkshop.olpc.SliderPuzzle.mo
  + po
  |  + SliderPuzzle.pot
  |  + pt.po

• SliderPuzzle.pot: The translation template, includes all relevant translatable items but no translations. Copy this file into a .po to start a new language translation.
• pt.po: The Portuguese translation source, bundled as reference for new language files creation.
• org.worldwideworkshop.olpc.SliderPuzzle.mo: The compiled translation for the language, in this case Portuguese (see the directory path leading to this file, locale/pt/LC_MESSAGES).

 There was a SliderPuzzle.mo file and an explanation that this would take the place of the org.*.mo file.
 It turns out the shortcut format was in fact a but in the sugar-jhbuild environment which has since been fixed.
 If we target builds 432, 542 and forth, only the fully qualified format is used.

Create a new translation language bundle

First thing you need to know about the language you are about to translate is the language code, which will be used as the name in the translation source and the directory when deploying the compiled translation. This is not something you can guess, the language code really needs to be a standards defined one.

The language code is a two (or more rarely three) letter code as specified in ISO 639 (http://www.gnu.org/software/gettext/manual/html_node/Language-Codes.html). Optionally you can add a locale to the language, which is the same as saying that you are translating for a specific country, not only for the language. These locale (or country) codes are two letter and uppercase as specified in ISO 3166 (http://www.gnu.org/software/gettext/manual/html_node/Country-Codes.html). Use an underscore to separate the two. Also check http://wiki.laptop.org/go/Locales.

If a system is configured to use a specific locale, for example in Brazil (which uses the pt_BR code), the system will first look for pt_BR, and failing that, searches pt and finally if that is not found either uses whatever default exists (does not apply translations, uses the translatable strings directly), which in our case is always english.

So, knowing what you are translating to, copy the SliderPuzzle.pot file into a new file with a name composed of the coutry code (and optional locale) and an extension .po. For example, copy it to sp.po for Spanish translation. You can now proceed to editing the translation bundle created.

Editing a translation bundle

Translation source files, the ones with the po extension, are the ones we edit. They can be edited on any text editor but be carefull with the encoding applied. The best and most fool-proof method is to use a specialized tool, like the above mentions poEdit. Using it you are sure that the translations are handled in the correct encoding (which you can specify) and it is actually much simpler to keep track of what still needs translation.

Each translatable item in the source po file is presented as at least 3 lines:

#: SliderPuzzleUI.py:502  <-- this is the location of the translatable string in the source code
msgid "My Pictures" <-- the translatable string, as found in the source
msgstr "Minhas Imagens" <-- the translated string

The only thing you need to change is the translated string, don't touch anything else unless you know what you are doing!

When the source code for an activity changes and the translatable items are altered, both the pot template and all existing translations are updated but, of course, only the translatable items are added, and the translations need to be manually inserted.

Compiling the translation bundle

On sugar-jhbuild

If you haven't done so before, visit the directory where you installed the sugar-jhbuild environment and run ./sugar-jhbuild shell. Next, go the bundle directory and do python setup.py genl10n

 The command used to be python setup.py genmo but was changed somewhere down the line.
 l10n stands for localization, 10 is the number of letters in that word between the l and the n.

On poEdit

Once you save the changes done, the compiled version is automatically created, leaving you with the task of putting it in the correct place and under the correct name. For example in Slider, move the po/pt.mo file into locale/pt/LC_MESSAGES/org.worldwideworkshop.olpc.SliderPuzzle.mo.

Using GNU's gettext utilities

This is what both Sugar and poEdit use under the hood. The command run for each language, in this example for Slider in Portuguese, is: $ msgfmt --output-file=locale/pt/LC_MESSAGES/org.worldwideworkshop.olpc.SliderPuzzle.mo po/pt.po

Updating a translation source to match an updated template

Whenever the translatable strings change, a new .pot template will be created. At this moment, and using a recent sugar-jhbuild environment, the *.po files are automatically updated, so there is nothing to be done here. All you need to do is edit the translations and compile them into *.mo files in the appropriate locations as described elsewhere in this document.

If you add, delete or change a translatable string in the source code, you can update the .pot file by calling sugar-jhbuild setup.py genpot. Some activities, specifically so in the Slider, use some special methods to create filesystem based translation strings, for directory listings of lessons in the particular case. This implies calling some script which can only be done in the sugar-jhbuild environment, only in linux for now.

Translating Lesson Plans and other such files

The lesson plans on Slider Puzzle and the text for the tabs on Teacher Center both follow a common structure. Other activities may or may not follow this same structure, but since these two were both developed by myself, here's how I go about making these texts translatable:

• Slider Puzzle has each lesson under a directory inside lessons.
• Teacher Center has each tab under a directory inside tabs.
• Each of the above (lesson or tab) has the actual texts in Abiword files, inside a directory with a name matching the tab label.

 The tab name is itself translatable in the translation bundles as described above.
 Actually, the tab name may have a single digit prefix to help in sorting tabs. This digit is removed after the sorting, so it does not appear in the tabs' label.

• The default (English) text is held in a file named default.abw.
• The available translations are kept each on its own file under the same directory as the default, and named _$lang_code$.abw, where $lang_code$ should be replace with the language code as described above.

 For example, the Portuguese translation will be called _pt.abw

Repackaging everything into a .xo bundle again

A .xo bundle is a ZIP file, with a defined set of files in for Sugar to use. Since we are not creating a bundle from scratch but rather altering an existing one, we can safely assume the structure is correct so, assuming you have unziped the bundle somewhere on your hard drive and you are looking at the top directory, just zip it back using the Send to -> Compressed (zipped) folder context menu action on Windows' file explorer or the zip command line tool on Linux.

Make sure the top directory is included in the zip file, for example in Slider Puzzle this would be SliderPuzzle.activity and everything inside it.

Rename the resulting zip file to have an xo extension (not mandatory right now, but once the school servers or other distribution methods are in place, that may be assumed) and you're ready to redistribute it.

Final thoughts

I have not mentioned the Mac platform. Let me just say it's nothing personal, but I don't have a Mac to try things on so I can't be of much help there. I'm sure some variation of the methods explained will work, though.

Be sure to provide the developer of the activity you translate or update content for with the changes, so they are not lost on the next release. This will eventually be solved by using a source versioning system, but still you may not have write permissions there so it's always good to keep the developer(s) up to speed with your changes.