This article is for reference purpose

The features described in this article are already implemented in the game. The article should describe how a certain aspect of the game currently works. You may of course edit this article to improve the description of the circumstances. Your opinions or improvement suggestions about the described aspects themself are of course appreciated, too. But please put these on the discussion page of this article to keep facts and fiction separated.

Translations in The Mana World are handled by the gettext system. This page presents an overwiew in the context of the game. Please refer to the manual for additional details.

Gettext for users

Translations are supposed to work out-of-the-box. If they are not, complain to the maintainer of your binary package. This section is dedicated to users compiling tmw themselves.

When configuring, the script should tell you that Native Language Support (NLS) is enabled. It just requires the presence of gettext on your computer. From there, just compile and install like you usually do, and it should work just fine. You just need to have properly set up your system with respect to locales. If console applications, e.g. man, are translated, then The Mana World will also be.

Note that the install part is mandatory for gettext to work. You cannot run the program from your compilation directory and expect it to be translated. Here is a work around:

 ./configure --localedir=$PWD/locale    # plus your special options
 make                                   # compile as usual
 cd po ; make install                   # whenever your .po file is modified

If you are not using the configure script, you need to tell your compiler to set two macros. The ENABLE_NLS macro should be 1. The LOCALEDIR macro should point to a directory structure xy/LC_MESSAGES/tmw.mo you created. The tmw.mo file is obtained by running the msgfmt tool.

Gettext for translators

The easiest way to translate TMW is to use the translation feature in Launchpad(link outdated--Nard 00:30, 16 August 2012 (CEST)). If you wish to translate the files manually, keep on reading.

When creating a translation for a not yet supported language, get the identifier of your language, as defined by ISO 639. It is usually two letter long. Let us suppose it is xy. Copy the po/tmw.pot to po/xy.po, and add xy to the po/LINGUAS file. That is all.

Now you can use your favorite text editor to modify the po/xy.po file. There are also a few dedicated editors. For example, gtranslator in Gnome and kbabel in KDE. The .po format is simple: on one msgid line, you read the original English sentence, on the next msgstr line, you write your translation. The encoding of your file should be UTF-8, as it is the internal format of the game, and we do not want it to waste time on converting between different charsets.

From time to time, modifications to the English strings will be merged to your .po file. When it happens, translate the new empty entries, and modify the old entries marked as fuzzy. Then submit the new file.

Sentences containing percent characters (especially when preceded by the c-format comment) need special care. They start special sequences that ends with a letter. The game will replace them by words (%s) or numbers (%d) or some other things. As a consequence, their order need to be strictly respected in order not to crash the game. If respecting the order makes it impossible to translate in your language, you can use positional markers instead:

 #, c-format
 msgid "%s owns %s in one language"
 msgstr "%2$s is owned by %1$s in another language"

Gettext for developers

When you just needs the translation of a literal string (one given between quotes), you can use the underscore macro.

 displayToUser(_("For long swords, size does matter."));

If you are in a context where you cannot execute this macro, you can delay the translation. Using a macro is still mandatory so that the strings can automatically be extracted for translators.

 static char const *msg = N_("For long swords, size does matter.");
 ...
 displayToUser(gettext(msg));

A point has to be stressed: Using the _() and N_() macros on anything else than a literal string, e.g. a variable or an expression, is plain wrong.

You should also avoid crafting sentences by concatenating words, as it makes it impossible to translate.

 displayToUser(std::string(id1) + _(" owns ") + id2);  # bad
 displayToUser(strprintf(_("%s owns %s"), id1, id2);   # good

Log messages and messages for internal errors (e.g. not caused by the user) should not be translated. They will usually be sent back as bug-reports, and we want to understand them.

Files containing translatable strings must have their name listed in po/POTFILES.in.

Gettext for translation manager

As .po and .pot files indicate at which positions the strings were extracted, adding or removing a single line to a source file would be enough to completely modify all the files of the po directory. As a consequence, a developer should never update the translations after modifying a source file, so as to not pollute the svn repository.

When preparing a release, during string freeze, one single developer (it does not have to be always the same one, but it can help in case of gettext version discrepancies) should be chosen to run

 cd po ; make update-po

and commit the resulting modifications. Then, just before releasing, once translators have sent or committed their modifications to .po files, it should be run again, so that packagers have access to updated files.