Childsplay Translation Mini-Howto

Stas Z

E-mail: childsplay@users.sourceforge.net

Release 0.66
May 10, 2003

Childsplay translation mini-HOWTO.

This document describes how to translate childsplay in your native language. The way to get childsplay 'talking' in your language is the same as with any other Linux application namely, gettext internationalization.(or i18n) The only exception is that we using python versions for extracting (pygettext.py) and compiling (msgfmt.py) of the text.

How i18n works. (Taken from the python lib. reference)

6.25.3 Internationalizing your programs and modules
Internationalization (I18N) refers to the operation by which a program is made aware of
multiple languages.
Localization (L10N) refers to the adaptation of your program, once internationalized,
to the local language and cultural habits. In order to provide multilingual messages for
your Python programs, you need to take the following steps:

1. prepare your program or module by specially marking translatable strings
2. run a suite of tools over your marked files to generate raw messages catalogs
3. create language specific translations of the message catalogs
4. use the gettext module so that message strings are properly translated

In order to prepare your code for I18N, you need to look at all the strings in your files.
Any string that needs to be translated should be marked by wrapping it in _('...') - i.e. a call
to the function _(). For example:

filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()

In this example, the string 'writing a log message' is marked as a candidate for translation, while
the strings 'mylog.txt' and 'w' are not.

The Python distribution comes with two tools which help you generate the message catalogs once you've
prepared your source code. These may or may not be available from a binary distribution, but they can be
found in a source distribution, in the Tools/i18n directory. (And in the childsplay/doc/po directory)

The pygettext program scans all your Python source code looking for the strings you previously marked as
translatable. It is similar to the GNU gettext program except that it understands all the intricacies of Python
source code, but knows nothing about C or C++ source code. You don't need GNU gettext unless you're also going
to be translating C code (e.g. C extension modules).

pygettext generates textual Uniforum-style human readable message catalog .pot files, essentially structured human
readable files which contain every marked string in the source code, along with a placeholder for the translation strings.
pygettext is a command line script that supports a similar command line interface as xgettext; for details on its use, run:

pygettext.py --help

Copies of these .pot files are then handed over to the individual human translators who write language-specific versions
for every supported natural language. They send you back the filled in language-specific versions as a .po file.
Using the msgfmt.py6.5 program (in the Tools/i18n directory), you take the .po files from your translators and generate
the machine-readable .mo binary catalog files.
The .mo files are what the gettext module uses for the actual translation processing during run-time.

How to translate these 'pot files'? We'll use as a example the childsplay.pot file. This file can be found in your childsplay tarball, in the childsplay/doc/po/ directory. Before we go further, some conventions,

 This is a example of source code

and this is, when you should type this in a x-term

The file memory.pot looks like this:

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2002 StasZ
# FIRST AUTHOR , 2002.
#
msgid ""
msgstr ""
"Project-Id-Version: 0.50\n"
"POT-Creation-Date: Sat Dec 14 13:59:26 2002\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME \n"
"Language-Team: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: ENCODING\n"
"Generated-By: pygettext.py 1.3\n"

#: memory.py:81
msgid "Memory"
msgstr ""

#: memory.py:89
msgid "Number of levels : 3"
msgstr ""

#: memory.py:87
msgid "Difficulty : 2-5 years"
msgstr ""

#: memory.py:84
msgid "The aim of the game:"
msgstr ""

#: memory.py:85
msgid "Classic memory game where you have to find pairs of cards."
msgstr ""

The first piece is some information and useful stuff, you can fill in some of the fields if you want , the

...charset=

field should always be left to ISO-8859-1,ISO-8859 -15, or some unicode coding. All the stuff in this section of the file is optional, so you can leave it as it is. The rest of the file is the important stuff, so now it's time to fire up your favorite text editor and load the childsplay.pot file. BTW, there are special po file editors like kbabel and poedit, but as the childsplay pot files are relatively small and they are always plain text files we can use any text editor.

Every part of the file consist of three lines.

#: memory.py:89
msgid "Number of levels : 3"
msgstr ""

The first line is a reference to the line number of the source code it can be found, you can use it to look for the context of the line, because all the lines are in random order in the pot file. The second line

msgid "Number of levels : 3"

is the original text from the source code and should be left alone. The third line is the line where the translated text belongs. So if we want to translate it to Dutch it would looks like this:

#: memory.py:89
msgid "Number of levels : 3"
msgstr "Aantal niveau's : 3"

It's important to try to maintain the length of the original text to avoid that the translated strings becomes to large for the widget or screen. In these cases it's best to try to put the piece of the string that's to long in the next string, if it's a multi lines text.

When you're done with the rest of the lines, save it as childsplay.po in some temp directory. (notice that they are po files from now one, it's just to separate it from the rest) Now you have two choices, send the translated po files to me and i will compile them and send them back to you or, you can compile them yourself and send them to me.

When you want to compile them get the program called msgfmt.py from the childsplay/doc/po directory and copy it to the directory containing your po files.

In a x-term cd to the directory where your files are and do

./msgfmt.py -o childsplay.mo childsplay.po

The generated mo file should be chown root:root and chmod 0644, now copy as root the file(s) to the appropriate directory, that should be /usr/local/share/locale/nl/LC_MESSAGES.

Start childsplay and if you have your locale setting on your system set to your language, childsplay should use your translation.