Difference between revisions of "HOWTO-Translate ScummVM GUI"

Revision as of 10:39, 20 August 2010

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.

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 (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:

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

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 perl and 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: nearly complete (305 messages translated, 3 approximative translations, 7 messages not translated).
French: nearly complete (299 messages translated, 16 approximative translations).
German: nearly complete (312 messages translated, 2 approximative translations, 1 messages not translated).
Hungarian: need work (33 messages translated, 21 approximative translations, 261 messages not translated).
Italian: nearly complete (311 messages translated, 3 approximative translations, 1 message not translated).
Russian: complete (315 messages translated).
Spanish: complete (315 messages translated).
Ukrainian: complete (311 messages translated, 4 approximative translations).

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.
Context based translation is not currently supported. For example only one translation for "None" can be provided and will be used everywhere "None" is used in the english GUI. In french depending on the grammatical gender of the word to which it refers (e.g. Extra Path, Soundfont) the translation should be different but for the moment it is not possible.

@@ Line 15: / Line 15: @@
 == Using the translation in ScummVM ==
-ScummVM does not use the po files directly. They need to be compiled in the application instead. To use or test your translation you will therefore need to compile ScummVM. This involves the following steps:
+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:
 # Get ScummVM source code if you don't already have it.
 # Make your translation available
 ##move or copy your po file into the scummvm source code po/ directory.
-## run "''make update-translations''" (you need to have [http://www.perl.org/ perl] and [http://www.gnu.org/software/gettext/ gettext] installed to do this).
+## run "''make translations-dat''" (you need to have [http://www.perl.org/ perl] installed to do this).
-# [[Compiling_ScummVM|Compile ScummVM]] (with translation support, which is the default).
+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 [http://www.perl.org/ perl] and [http://www.gnu.org/software/gettext/ gettext] installed to do this). This will also automatically regenerate the ''translations.dat'' file.
 == Proposing your translation to the team ==