Open main menu

HOWTO-Translate ScummVM GUI

Revision as of 23:52, 13 September 2010 by Criezy (talk | contribs) (Add list of po file editors)

This page contains instructions to translate the ScummVM GUI.Translations from the community are welcome and should be proposed on the patch tracker.

Creating or Updating a translation file

Translations can be produced with the use of the GNU gettext tools. To create or edit a translation file you can for example use Emacs PO-Mode or Poedit which are both free and available for various platforms. See Editing Tools for more tools.

Before starting a translation it would be a good idea to check the list of existing translations and to contact the team on the forum or IRC to know if other persons are already working on a translation for this language. That way if there is already a translation in the work you can avoid duplicate efforts and work together.

For a new translation, use scummvm.pot (from the source code repository) as a template and fill out the header. Then you just have to translate the strings and save your work in a po file.

Please note that:

  • The current implementation in ScummVM supports only single byte encoding. So don't use UTF-8 encoding for the po file. Latin1 (ISO 8859-1) is fine for most western european languages.
  • Some strings are attached to a context (defined with msgctxt "context string" before the msgstr "translated text" in the po files). This means the same english string can be translated differently depending on the context. For example:
    • "None" is defined with two different contexts: "path" and "soundfont". Therefore the translation can be different if needed depending if "None" refers to a path or a soundfont.
    • Some strings are defined both with the "lowres" context and without a context. If the "lowres" string is left empty it will use the translation for the same string without a context. But it can be defined to a shorter translation if needed. The "lowres" translation, if defined, is used when the GUI is in 1x mode (e.g. resolution of 320x200 or 320x240). The translation not associated to a context is used when GUI is in 2x and 3x modes.
  • Some strings (e.g. button labels) contain the definition of a shortcut key using the ~ characters. For example "~S~tart" will display "Start" and use 'S' has a shortcut.
  • '%' character in a string denotes an argument. For example '%d' is an integer and '%s' is a string. They need to be kept unchanged in the translated string and furthermore their order has also to be kept.

Using the translation in ScummVM

ScummVM does not use the po files directly. They need to be transformed into a translations.dat file instead. To use or test your translation you will therefore need regenerate that file. This involves the following steps:

  1. Get ScummVM source code if you don't already have it.
  2. Make your translation available
    1. move or copy your po file into the scummvm source code po/ directory.
    2. run "make translations-dat".

This will update the translations.dat file in gui/themes/. For ScummVM to find it you might have to copy it somewhere else (e.g. in the directory where the ScummVM executable resides).

You can also update the template files and all po files from the source code (to make sure the list of messages to translate is up to date). To do so, in the ScummVM source code directory type "make update-translations" (you need to have gettext installed to do this). This will also automatically regenerate the translations.dat file.

Proposing your translation to the team

You are welcome to propose your new translations (or an update of an existing translation) on our patch tracker.

Existing translations

Currently the following translations are present in our repository. They may not be complete and improved translations for these languages are welcome.

  • Catalan: 346 string translated, 7 fuzzy translations, 1 string not translated
  • German: 346 string translated, 8 fuzzy translations
  • Spanish: 312 string translated, 41 fuzzy translations, 1 string not translated
  • French: 353 string translated, 1 fuzzy translation
  • Hungarian: 32 string translated, 39 fuzzy translation, 283 strings not translated
  • Italian: 347 string translated, 7 fuzzy translations
  • Russian: 346 string translated, 8 fuzzy translations
  • Ukrainian: 308 string translated, 45 fuzzy translation, 1 string not translated

Limitations

  • As noted above, only single byte character encoding is supported.
  • The limitation on reordering format specifiers for fields (the '%d' and '%s' etc. above) may make it difficult to translate certain phrases to some languages, due to difference in grammar. GNU gettext has means to solve this but it is not currently known whether this works (and is portable to all target platforms) in ScummVM.

FAQ

What's a fuzzy string?

It's a string calling for translator revision. For example, if an English string gets a small change in the source code, or if a new english string similar to an existing one is added, the translation of that string is marked as fuzzy.

Translations of fuzzy strings are not included in the translations data file. The translator needs to validate it (by removing the fuzzy marking) and possibly fixing the translation if needed. Only then will it be used in ScummVM.

What does c-format means?

The c-format flag indicates that the untranslated string and the translation are supposed to be C format strings (as used by printf()). These strings have format specifiers (e.g. %d, %s) to indicate that numbers or sub-strings are inserted at run time into the string. These specifiers should be kept in the translation in the same order as they are present in the english string (see Limitations).

What are "Plural-forms"?

Some languages have different word forms for different numbers of things (for example in English we have "1 thing" but "2 things"). The rules are different for different languages. You can find them here.

ScummVM however does not use that information (yet). But it does not hurt to have the correct plural-forms description in the po file.

My language needs a different charset to be displayed correctly

The fonts are included in the theme packages and each charset (e.g. ISO 8859-1) needs its own version of the fonts. The Modern Theme for example currently contain the fonts for ISO 8859-1 (used by most Western European languages) and ISO 8859-5 (used for the Russian and Ukrainian translations). If you language nedds to use a different charset, then the font for that charset will need to be added to the Theme.

TODO: explain how to generate bdf fonts for a given charset.

Editing Tools

There are several tools to work with .po files: