UFOAI Translation

UFOAI uses text messages: weapon names, mission descriptions, menu labels, credits, etc. At this time, all text messages are written in English. Many forum participants have requested that these messages be translated into their native language, and a good proportion of these requests have included offers to assist in the translation. Therefore the UFOAI project should investigate what and how to translate UFOAI. In January 2005 I asked Sacrusha if I could work on the UFOAI code. Sacrusha said I could and asked me to look into translation. This paper explains the results of four weeks of experimentation translating various parts of the UFOAI TD1 game.

What needs to be translated?

Translation is typically about changing character strings from one language to another. UFOAI contains lots of strings, but many of them don't need to be translated. At this time, I recommend that the project limit translation to text messages which a player would see while playing the game. This includes two types of text messages: text strings and text images. Text strings are character arrays, all of which are defined in ascii files in the base/ufos directory. Text images are characters which appear in png or jpg images. These images are stored in the base/pics directory. Both text strings and text images are accessed by the UFOAI game engine's menu system.

If the objective is only to translate text messages that a player would see while playing the game, then none of the strings in the UFOAI game engine itself need to be translated. For instance, error messages, cvar names, cvar values, console command names, and console messages don't need to be translated – at least not at this time.


If there is a standard translation tool for F/OSS projects, it is probably gettext. So any free software project which intends to implement translation should probably start with gettext. In its simplest usage, a programmer would modify the print statements slightly to include a call to the gettext library, like this.

Original code:


Modified code:


The _(string) usage is defined in a macro like this:

#define _(String) gettext (String)

When the modified code executes, first the gettext function looks up the string “hello” in its translation database, and returns a string pointer to the translated string. Then the printf function displays the translated string.

There are two problems with this system when applied to UFOAI. The first problem is that the UFOAI game engine uses string pointers to keep track of the text strings. We can still use gettext, but it is harder than the simple example shown above. We could either do the translation when the menu system reads the strings in the base/ufo files by modifying the MN_Parse_Action function. Or we could implement the translation when the render engine updates the display; probably by modifying the Draw_PropString function. This would be less messy than fiddling with the menu parsing code, but might increase the time required to render each frame, thereby decreasing the number of frames per second.

The second problem is that some text messages are included in menu images. We could still use gettext. For instance, consider the base/pics/loading.pcx image. We could create a second image, base/pics/chargement.pcx, then we use gettext to translate the filenames. Again, we could do this translation either when the menu system parses the image names from the base/ufos files or when the rendering system displays them. The disadvantages are the same as for string pointers, with the added disadvantage that we aren't really using gettext the way it is intended to be used – we aren't translating messages, we are translating file names. Which might seem nit picky, but unnecessarily complicated code often leads to bugs.

A Simple Alternative

After experimenting with gettext for a few weeks, I thought about a simple alternative. All the text strings are stored in the base/ufos directory. All the text images are stored in the base/pics directory. The idea is this: have different ufos and pics directories for each language, then symlink to the correct directory. For instance, the base directory might look like this:

lrwxrwxrwx   1 andrew andrew    7 2005-02-10 15:43 pics -> pics_en
drwxr-xr-x   2 andrew andrew 4096 2005-02-10 15:43 pics_de
drwxr-xr-x   6 andrew andrew 4096 2004-12-25 14:44 pics_en
drwxr-xr-x   2 andrew andrew 4096 2005-02-10 15:43 pics_es
drwxr-xr-x   2 andrew andrew 4096 2005-02-10 15:43 pics_it
drwxr-xr-x   2 andrew andrew 4096 2005-02-10 15:43 pics_ru
lrwxrwxrwx   1 andrew andrew    7 2005-02-10 15:44 ufos -> ufos_en
drwxr-xr-x   2 andrew andrew 4096 2005-02-10 15:43 ufos_de
drwxr-xr-x   2 andrew andrew 4096 2005-02-02 20:52 ufos_en
drwxr-xr-x   2 andrew andrew 4096 2005-02-10 15:43 ufos_es
drwxr-xr-x   2 andrew andrew 4096 2005-02-10 15:43 ufos_it
drwxr-xr-x   2 andrew andrew 4096 2005-02-10 15:43 ufos_ru

Each supported language keeps its files separate ufos and pics directories. Changing languages is implemented simply by changing the symlink. This could be done within the UFOAI game itself, by a setup utility, or manually. If a target OS does not support symlinks, then the directories could be copied.

This approach has the advantage of being very simple. It does not slow down the rendering engine or complicate the menu code. Languages can be added to the base tree in a modular fashion. The main disadvantage is that every language requires a separate copy of the base/pics directory, which at this time is about 2MiB when zipped. So if UFOAI were to support 20 languages, then the download size would increase by 38 MiB.

UFOAI Font and International Character Support

Regardless of whether UFOAI uses the gettext or “simple” approach, at this time the UFOAI engine only renders the characters from the two fonts shown below. It might be useful to add another font containing international characters, or to extend the font to include “extended ASCII” characters.

It would also be helpful if the UFOAI project team specified a font to use in the base/pics files.

Where do we go from here?

One of the advantages of the simple approach is that you don't need anyone's approval or co-operation to do it – you can just start translating. So I would suggest that if you are interested in translating UFOAI to your native language, then launch your favourite text editor and start translating the files in the base/ufos directory. If lots of people submit language sets, and the download becomes too large, then it's pretty easy to port the translated strings and images to the gettext system.

We also need Herby's comments about the feasibility of adding international characters to the fonts.

A.G. Howlett (radagast),
10 February 2005