<%! title = "Translation Guide" uses_toc = True %> <%inherit file="/page.mako" /> <%def name="preface()">

Portato supports native languages. Nevertheless the translations into these languages have to be created. This page shows how to add a new translation or how to extend an existing translation.

<%self:h2>Short introduction about NLS in Linux

All translatable strings of a program are listed in a *.pot file. For each translation a single $LANG.po file is created, which holds each translatable string and the corresponding translation. During installation these po-files are compiled into .mo files, which are then used to get the translations during runtime. If you are wondering, what is meant by $LANG: It is a code defining a language. It normally consists of two letters as defined by ISO 639-1, e.g. en, de, fr... If you want to differentiate between different kinds of one language, you append a modifier: en_US, en_GB, de_DE, de_AT etc.

<%self:h2>Programs you (might) need

The recommended program for the translation is app-i18n/poedit, however you may want to try out kde-base/kbabel or app-text/gtranslator. Another simple option would be to use your normal text editor :)

This guide will assume you are using poedit.

<%self:h2>Getting the sources

You do need the sources to make translations, as the installed program is not sufficient. Please see the development page for how to get them and what is needed to run portato locally.

<%self:h2>Updating an incomplete translation

If there is a translation for your language already, then open the $LANG.po file in portato's i18n/ directory with poedit. Select "Update from POT file" from the "Catalog" menu, then choose the messages.pot file in the i18n/ directory. Untranslated strings will be highlighted and placed at the top of the list. Translate them and save the file!

<%self:h2>Creating a new translation

Open poedit and Select "New catalog from POT file" from the "File" menu, and choose the messages.pot file in portato's i18n/ directory. Translate, then save the file (also in the i18n/ directory) as $LANG.po.

<%self:h2>Placeholders

The translatable strings in the messages.pot catalogue and the $LANG.po files are partially in Python's string format, partially in GTK's. The following items should be included in translated strings as placeholders for names or figures:

Html-Tags (${"some_text" | h}) should be kept as is and only the text in between has to be changed.
In addition, the underscore (_) is used to indicate that the next character will be used as the accelerator key. When the user presses "CTRL" + this key, it will perform the item's action. These are not required, but if you use them the characters chosen must all be different.

Strings like "gtk-quit", "gtk-cancel" etc. must not be translated.

<%self:h2>Test your translation

Before testing, run the "pocompile" script in the portato directory, which will compile all the .po files in i18n/ into .mo files and place them in the necessary subdirectories ($LANG/LC_MESSAGES):

<%self:hl lang="bash"> ./pocompile.sh

Now you can run the local portato version in your language (the -F makes portato run as the current user and thus saves you having to enter your root-password over and over again):

<%self:hl lang="bash"> ./portato.py -F

If you are not seeing your language, make sure the environment variable "LANG" is set to your language code. For example, to run portato using the German translation:

<%self:hl lang="bash"> LANG="de_DE" ./portato.py -F <%self:h2>Submit your translation

The easiest way to submit your translation is to create a bug in the bugtracker or to send a mail to portato@necoro.net.

<%self:h2>I found an untranslatable string

Post a bug in the bugtracker. Include the untranslatable string and where in Portato you came across it. It's easy for us to mark the strings for translation, but we may have missed some!

<%self:h2>GUIs suck - I want to use a text editor

The .po files are plain text files. If you don't want to use poedit for some reason, these gettext commands might come in handy:
Update a .po file from the messages.pot file:

<%self:hl lang="bash"> msgmerge $LANG.po messages.pot > newpofile.po

Create a new .po file from the messages.pot file:

<%self:hl lang="bash"> msginit -i messages.pot -l $LANG