Difference between revisions of "HOWTO-Translate ScummVM GUI"

Latest revision as of 00:31, 26 March 2021

This page contains instructions to translate the ScummVM GUI, the QuickStart file and/or the README file.Translations from the community are welcome and should be proposed on the patch tracker.

Creating or Updating a translation file

We now have a web site where you can directly add new translations and update existing ones: https://translations.scummvm.org

Please note that:

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.

The recommended way to translate ScummVM is to use the https://translations.scummvm.org web site mentioned above.

You can also download the translations on your computer and work locally. You can get the existing translation files either from our GitHub repository(https://github.com/scummvm/scummvm/tree/master/po - click on the file you want and use the "raw" or "View Raw" button) or from our translation web site (https://translations.scummvm.org). When working locally, 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. Then visit https://translations.scummvm.org to upload your updated po file.

Default users of the website can make suggestions and vote on the suggestions, but they cannot save translations or create new translations. Only official translators can start a new translations, accept suggestions and save changes to a translations. Thus if you want to start a translation for a new language you will need to speak to us. Also 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.

You can also start your translation effort offline before it is added to the website by using the 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. To download the file, click on scummvm.pot and then the raw or View Raw button. If this tries to display the file in your browser, do a right click on that button and select Save target file as... (the working might be different depending on the browser). You might also need to remove any extension added by your browser (for example for me Safari downloads the file as scummvm.pot.pps, apparently believing it to be a MS Powerpoint file).

You should also set the 'X-Language-name: Name\n' field in the header of the po file to indicate the name of the language in the ScummVM GUI. If not set, it will use the language code instead (for example 'de_DE' or 'fr_FR').

Translating the README or QuickStart file

You can also provide a translation of the README file or of the QuickStart file to distribute with ScummVM. The QuickStart file is actually an excerpt of the README file, so you can start by translating that file and later when you have more time translate the full README file.

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 to regenerate that file.

Generate Translations Data file outside of ScummVM code repository

This is the simplest option. Simply grab below one or the pre-compiled binary for the creation tool or compile it yourself. If you want to compile it yourself, you can get the source code from the ScummVM source code repository (in tools/create_translations/).

WARNING: The create_translations tools linked below are outdated and will not work with a recent version of ScummVM

Then place the creation tool and all the po translations files you want to include in the generated data into the same directory and run the following command on the command line:

./create_translations *.po

If you have codepages present in po - which enable other charsets from languages, you will also need to include it as a command-line argument, along with *.po, like this:

./create_translations *.po *.cp

For Windows, you can simply run the included bat file.

This will generate a translations.dat file that you need to place in your ScummVM Theme path.

Generate Translations Data file from ScummVM code repository

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".

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

The preferred way to propose your new translation (or an update to an existing one) is to use a pull request on GitHub. As a simpler alternative you can also use our patch tracker. Please select the Translation category for the tracker item.

Existing translations

See https://translations.scummvm.org/projects/scummvm/scummvm/

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 is 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).

Why are some strings preceded by '#~'?

They are obsolete strings that were used in the past in ScummVM but have since been removed. They are kept in the file to help translators (e.g. if the string is added back or a similar string is added), but will not be used in ScummVM. There is therefore no need to translate those.

Why is there strange '\' in some strings?

The backslash character \ is used in C/C++ strings to protect the following character or for special characters. They may therefore be present in strings to translate but will not appear as is to the users. Currently the following sequence are supported by the translation creation tool. You may keep the one you encounter, remove some of them or even add some of them in translated strings. Usually you will want to keep them however.

In string	Appear to user as
\n	line break
\t	tabulation
\\	\ (single backslash)
\'	' (single quote)
\"	" (double quote)

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:

poEdit (Multiplatform)
Emacs with po-mode (Multiplatform)
Vim with PO plug-in (Multiplatform)
Lokalize (Unix KDE)
GTranslator (Unix Gnome)
Virtaal (Multiplatform)

Contacting the Team

There are several ways you can contact the team for translations related question. You can visit the #scummvm IRC channel on irc.freenode.net, use the forum or send an email to translation(AT)scummvm(DOT)org

@@ Line 2: / Line 2: @@
 == Creating or Updating a translation file ==
-Translations can be produced with the use of the [http://www.gnu.org/software/gettext/ GNU gettext tools]. To create or edit a translation file you can for example use [http://www.gnu.org/software/hello/manual/gettext/PO-Mode.html Emacs PO-Mode] or [http://www.poedit.net/ Poedit] which are both free and available for various platforms. See [[#Editing Tools|Editing Tools]] for more tools.
+We now have a web site where you can directly add new translations and update existing ones: https://translations.scummvm.org
-Before starting a translation it would be a good idea to check [[#Existing Translations|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 [https://github.com/scummvm/scummvm/tree/master/po 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. To download the file, click on scummvm.pot and then the ''raw'' or ''View Raw'' button. If this tries to display the file in your browser, do a right click on that button and select ''Save target file as...'' (the working might be different depending on the browser). You might also need to remove any extension added by your browser (for example for me Safari downloads the file as ''scummvm.pot.pps'', apparently believing it to be a MS Powerpoint file).
-If a translation already exists for you language, you can get the up to date po file from [https://github.com/scummvm/scummvm/tree/master/po this same source code repository]. As for the template file, you need to click on the file you want and then use the ''raw'' or ''View Raw'' button. You may need to do a right click on the button to save the file on your computer instead of displaying it in the browser. Also some browser may add a ''.txt'' extension that you will need to remove. Before proposing changes to the team (or committing changes if you have commit access) you should let the primary translator know of the changes. You will find contact details for the primary translator(s) in the header of each 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.
@@ Line 17: / Line 10: @@
 * 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.
+The recommended way to translate ScummVM is to use the https://translations.scummvm.org web site mentioned above.
+You can also download the translations on your computer and work locally. You can get the existing translation files either from our GitHub repository(https://github.com/scummvm/scummvm/tree/master/po - click on the file you want and use the "raw" or "View Raw" button) or from our translation web site (https://translations.scummvm.org). When working locally, translations can be produced with the use of the [http://www.gnu.org/software/gettext/ GNU gettext tools]. To create or edit a translation file you can for example use [http://www.gnu.org/software/hello/manual/gettext/PO-Mode.html Emacs PO-Mode] or [http://www.poedit.net/ Poedit] which are both free and available for various platforms. See [[#Editing Tools|Editing Tools]] for more tools. Then visit https://translations.scummvm.org to upload your updated po file.
+Default users of the website can make suggestions and vote on the suggestions, but they cannot save translations or create new translations. Only official translators can start a new translations, accept suggestions and save changes to a translations. Thus if you want to start a translation for a new language you will need to speak to us. Also starting a translation it would be a good idea to check [https://translations.scummvm.org/projects/scummvm/scummvm/ 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.
+You can also start your translation effort offline before it is added to the website by using the scummvm.pot (from [https://github.com/scummvm/scummvm/tree/master/po 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. To download the file, click on scummvm.pot and then the ''raw'' or ''View Raw'' button. If this tries to display the file in your browser, do a right click on that button and select ''Save target file as...'' (the working might be different depending on the browser). You might also need to remove any extension added by your browser (for example for me Safari downloads the file as ''scummvm.pot.pps'', apparently believing it to be a MS Powerpoint file).
+You should also set the 'X-Language-name: Name\n' field in the header of the po file to indicate the name of the language in the ScummVM GUI. If not set, it will use the language code instead (for example 'de_DE' or 'fr_FR').
 == Translating the README or QuickStart file ==
@@ Line 23: / Line 26: @@
 == 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.
+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 to regenerate that file.
 === Generate Translations Data file outside of ScummVM code repository ===
 This is the simplest option. Simply grab below one or the pre-compiled binary for the creation tool or compile it yourself. If you want to compile it yourself, you can get the source code from the [http://scummvm.svn.sourceforge.net/viewvc/scummvm/scummvm/trunk/ ScummVM source code repository] (in tools/create_translations/).
+<pre style="color: red">WARNING: The create_translations tools linked below are outdated and will not work with a recent version of ScummVM</pre>
 * [http://wiki.scummvm.org/images/7/75/Create_translations_windows.zip create_translations tool for Windows]
 * [http://wiki.scummvm.org/images/8/83/Create_translations_mac_10.6.zip create_translations tool for Mac OS X Snow Leopard]
@@ Line 34: / Line 38: @@
   ./create_translations *.po
-For Windows you can simply run the included bat file.
+If you have codepages present in po - which enable other charsets from languages, you will also need to include it as a command-line argument, along with *.po, like this:
+ ./create_translations *.po *.cp
+For Windows, you can simply run the included bat file.
 This will generate a translations.dat file that you need to place in your ScummVM Theme path.
@@ Line 50: / Line 57: @@
 == Proposing your translation to the team ==
-You are welcome to propose your new translations (or an update of an existing translation) on [http://sourceforge.net/tracker/?group_id=37116&atid=418822 our patch tracker]. Please select the ''Translation'' category for the tracker item.
+The preferred way to propose your new translation (or an update to an existing one) is to use a pull request on [https://github.com/scummvm/scummvm GitHub].
+As a simpler alternative you can also use [http://sourceforge.net/tracker/?group_id=37116&atid=418822 our patch tracker]. Please select the ''Translation'' category for the tracker item.
 == Existing translations ==
-Currently the following translations are present in [https://github.com/scummvm/scummvm/tree/master/po our repository]. They may not be complete and improved translations for these languages are welcome. To download the file from the link above, you need to click on the file you want and then use the raw or View Raw button. You may need to do a right click on the button to save the file on your computer instead of displaying it in the browser. Also some browser may add a .txt extension that you will need to remove.
+See https://translations.scummvm.org/projects/scummvm/scummvm/
-<br>
-{| cellspacing="2" cellpadding="5" width=100% class="chart color4"
-|+ Available translations
-|- class="color4"
-! width=100 align=center|Language !! Translated strings !! Fuzzy translations !! Strings not translated
-|- class="color2" align=center
-| align=left|Belarusian ||666 ||   10 || 29
-|- class="color0" align=center
-| align=left|Catalan     || 666 ||  10 || 29
-|- class="color2" align=center
-| align=left|Czech       || 674 || 5  || 26
-|- class="color0" align=center
-| align=left|Danish      || 654 || 14 || 37
-|- class="color2" align=center
-| align=left|German     || 705 || 0  || 0
-|- class="color0" align=center
-| align=left|Spanish     || 654 || 14   || 37
-|- class="color2" align=center
-| align=left|Basque     || 620 || 21   || 64
-|- class="color0" align=center
-| align=left|Finnish     || 652 || 10   || 43
-|- class="color2" align=center
-| align=left|French       || 705 || 0   || 0
-|- class="color0" align=center
-| align=left|Galician     || 705 || 0  || 0
-|- class="color2" align=center
-| align=left|Hungarian || 705 || 0   || 0
-|- class="color0" align=center
-| align=left|Italian       || 705 || 0   || 0
-|- class="color2" align=center
-| align=left|Norwegian Bokm&aring;l || 682 || 4 || 19
-|- class="color0" align=center
-| align=left|Norwegian Nynorsk || 443 || 64 || 198
-|- class="color2" align=center
-| align=left|Polish       || 652 || 14  || 39
-|- class="color0" align=center
-| align=left|Brazilian   || 595 || 34   || 76
-|- class="color2" align=center
-| align=left|Russian    || 666 || 10    || 29
-|- class="color0" align=center
-| align=left|Swedish    || 654 || 14   || 37
-|- class="color2" align=center
-| align=left|Ukrainian  || 666 || 10    || 29
-|}
-Some people has also offered to work on new translations. These are the ones we are aware of:
+<div id="mw-scummvm-weblate-status"></div>
-<br>
-{| cellspacing="2" cellpadding="5" width=100% class="chart color4"
-|+ Known interests
-|- class="color4"
-! width=100 align=center|Language !! Person who contacted us
-|- class="color2"
-| Croatian   || RedDragon
-|- class="color0"
-| Dutch      || ground
-|- class="color2"
-| Finnish   || raina
-|- class="color0"
-| Portugal Portuguese || Jogait
-|}
 == Limitations ==