Translation
OpenOrienteering Mapper supports localization. This page gives an overview and hints to both translators and programmers.
All issues with label translation
The user interface is translated to the following languages:
| Language | Code | State |
|---|---|---|
| Čeština (Czech) | cs |  |
| Deutsch (German) | de |  |
| English (plural forms only) | en |  |
| Español de España (Spanish) | es |  |
| Eesti (Estonian) | et |  |
| Français (French) | fr |  |
| Italiano (Italian) | it |  |
| Latviešu (Latvian) | lv |  |
| Magyar (Hungarian) | hu |  |
| Nederlands (Dutch) | nl |  |
| Norsk bokmål (Norwegian Bokmål) | nb |  |
| Polski (Polish) | pl |  |
| Portuguêse do Brazil (Brazil) | pt_BR |  |
| Русский (Russian) | ru |  |
| Suomi (Finnish) | fi |  |
| Svenska (Swedish) | sv |  |
| Українська (Ukrainian) | uk |  |
| 日本語 (Japanese) | ja |  |
Translation efforts should first focus on standard user interface items such as menu entries, window titles, button labels etc.
Translation online with Weblate
Editing translations online on Weblate is the most convenient way to start contributing. Weblate provides a number of checks and other interesting features. There is an online translators guide. Even if not a registered user, you may provide suggestions which will eventually be accepted or rejected by registered users.
You can easily register/login with your Github account. Registered users can create and edit translations, and subscribe for notifications on various events regarding there language and projects. Registered users may also add comments to either the source string (e.g. suggestions to fix typos and change punctuation, or requests for clarification), or to the translation for a particular language (discussion with or documentation for other translators). These comments are available (and should be read) when editing translations.
When saving a translation, translators may add a commit message. However you should not use this field unless you know what you are doing. These messages are recorded more or less permanently in the project's revision history.
Unfortunately, there is no easy way to test the translations until they eventually arrive in an unstable build.
Attention: As long as Weblate produces quite different output than the Qt tools (https://github.com/nijel/weblate/issues/1118), it is not recommended to use Qt Linguist: It will lead to some noise in the git change log.
Qt Linguist can be installed as part of the Qt SDK installer or as part of Linux distributions' Qt5 development tools packages (e.g. qttools5-dev-tools). Linguist is also included in our unstable Windows package.
You may either use git to clone our source code repository, or download and extract a ZIP-Archive of the master branch. For every supported language, there is a .ts-file in the translations directory, which contains both the strings to be translated and the actual translations.
To start the translation for a new language offline, you can start with the template .ts-file. You can submit the new translation with a pull request or an issue on Github.
To update or modify an existing translation you can download the latest version from the translations directory or use git to checkout the source code including the translations directory:
git clone https://github.com/OpenOrienteering/mapper.git
You can submit the updated translation with a pull request or an issue on Github.
When the developers add new strings to the source code, these strings have to be added to the the .ts-files. This is done by calling the lupdate program with the proper sources and targets. For platforms where /bin/sh is available a script translations/update-translations.sh is provided which automates that process.
Warning: Since the .ts-file contains the translated strings, you might loose translations which are not yet in the git repository when you download a fresh copy of the file from the git repository. Make a backup of your work if you are in doubt. For merging translations see below.
To test your translation, you must generate a .qm file and make it available to your Mapper program. Your can save a .qm file from Qt Linguist. Than it should be enough to put the resulting .qm file to the "translations" subdirectory of the Mapper executable directory, or to select it from the settings dialog. The file must be named OpenOrienteering_YOURLOCALE.qm (e.g. OpenOrienteering_de.qm). The desired language can be chosen in the settings dialog (menu "File" > "Settings...").
Some strings in the user interface come from the Qt library which is used by Mapper. Examples are the standard dialog buttons (OK, Cancel, Help, etc.) which are used in many places such as the settings dialog.
Unfortunately, the library's translation is rather incomplete at the moment. So we provide another template which can be used to provide a minimal translation of Qt. The download is here: template .ts-file
-
Learn about the Qt translation framework from a programmer's point of view.
-
Add tr("....") to strings to be translated. In case of UTF-8 characters which are not part of the Latin-1 charset, use trUtf8("...") instead.
-
For standard dialog box buttons, use QDialogButtonBox with the appropriate StandardButtons. This class will use the platform look and feel, and it removes the necessity to introduce translatable string for standard buttons.
-
Keep translations in mind when constructing phrases:
- Find a good phrase before first commit.
- Don't introduce many variants of phrases when standardization is easily possible.
-
Even units of measurement might need translation. For disambiguation, supply a second parameter to tr(), e.g.
tr("m", "meters")
- Translations (.ts files) shall be saved in the translations directory.
- Translations must be added to the Mapper_TRANS variable in CMakeLists.txt.
- Translations may be updated by calling "make Mapper_translations_update" (for all translations and the template), "make Mapper_OpenOrienteering_XX_update" (for language XX), or "make Mapper_OpenOrienteering_template_update" (for the template only).
Sometimes it may be useful to merge several translations into a single file, e.g. to provide a single download file which contains both Mapper and Qt translations. This can be achieved with the lconvert tool from the Qt SDK. This is a versatile tool which actually can convert a number of different formats.