This page describes what developers need to do to make some part of the ScummVM GUI translatable. Therefore it concerns in particular the porters and developers working on the GUI.
Mark translatable strings in the source code
In order to make a string translatable you have to use one of the following pseudofunctions in your code:
- _(char *) - Main way to mark strings. You need it in majority of cases.
- _c(char *, char *) - Another way to mark strings. It attaches the string to a context so that we can have different translations for the same string. The second argument is the context.
- _s(char *) - Function used to mark static string constants. For instance, when you have static arrays which need to be translated. In this case you mark these strings with _s(), and then use _() or _c() at the place where you need to perform the substitution.
- _sc(char *, char *) - Another way to mark static string constants. It attaches the string to a context so that we can have different translations for the same string. The second argument is the context.
- DECLARE_TRANSLATION_ADDITIONAL_CONTEXT(char *, char *) - Declare a string (first argument) to translate in a given context (second argument).
An example to illustrate the difference between _() and _s():
- _() is a function, and is used within code. So it's used in cases like this:
<syntax type="C++"> foo(_("Bar")); </syntax>
- _s() is a wrapper, used with static string constants. So it's used in cases like this:
<syntax type="C++"> char *foo {
_s("bar"),
_s("baz")
}; </syntax>
If you want to give some additional explanations to the translators, or your string could be understood in a different ways, it is recommended to precede it with a comment tagged I18N.
<syntax type="C++"> // I18N: This is explanation to the line below and will be included in .pot and .po files static const char *foo = _s("Some translatable text"); DECLARE_TRANSLATION_ADDITIONAL_CONTEXT("Some translatable text", "lowres")
StaticTextWidget *bar = new StaticTextWidget(this, "name", _(foo), _("Some other translatable text for the tooltip")); StaticTextWidget *bar = new StaticTextWidget(this, "name", _c(foo, "lowres"), _("Some other translatable text for the tooltip"));
StaticTextWidget *path = new StaticTextWidget(this, "name", _("None", "path")); // I18N: Some more explanations for the translators StaticTextWidget *soundfont = new StaticTextWidget(this, "name", _("None", "soundfont")); </syntax>
In the above example foo can be translated differently depending if it is attached to the context "lowres" or not. "None" can also be translated differently depending if it refers to a path or a soundfont.
Update the translation template file
- All the files that contain translatable text should be listed in the po/POTFILES file. So if you are adding translatable text into a file, you should make sure that file is listed in POTFILES and otherwise add it to the list.
- You should then update the scummvm.pot template file by running "make updatepot". You need to have the gettext tool installed to run that command.
The translations are transformed into a translations.dat file (which can be done by executing "make translations-dat"), and the gettext tools are not needed for the compilation or executation of ScummVM. They are only needed to update the scummvm.pot template file and the translations when translatable strings are added, removed or modified in the source code.
Translations file format
See Translations Data File Format for a description of the format of the translations.dat file.
TO DO
- Updating interface without restart. This will require moving much code to reflowLayout() for all dialogs and is a big piece of work.
- Situations with strings not fitting into widgets. No code around that. Suggestions are welcome.
- Behavior for non-ASCII hotkeys (surrounded by tildes) is undefined and was not even tested.