Translation
OpenOrienteering Mapper supports localization. This page gives an overview and hints to both translators and programmers.
Everything okay.
Weblate: Failing checks
Weblate: Source strings to check
Weblate: Ignored checks
Github:
The user interface is translated to the following languages:
| Language | Code | State (Mapper) | State (Symbol sets) | State (Qt) |
|---|---|---|---|---|
| Čeština (Czech) | cs |  |
 |
qtbase_cs |
| Dansk (Danish) | da |  |
 |
qtbase_da |
| Deutsch (German) | de |  |
 |
qtbase_de |
| English (plural forms only) | en |  |
n/a | n/a |
| Español de España (Spanish) | es |  |
 |
qtbase_es |
| Eesti (Estonian) | et |  |
 |
|
| Esperanto | eo |  |
 |
 |
| Français (French) | fr |  |
 |
qtbase_fr |
| עברית (Hebrew, right-to-left) | he |  |
qtbase_he | |
| Bahasa Indonesia (Indonesian) | id |  |
 |
|
| Italiano (Italian) | it |  |
 |
qtbase_it |
| Latviešu (Latvian) | lv |  |
qtbase_lv | |
| Magyar (Hungarian) | hu |  |
 |
qtbase_hu |
| Nederlands (Dutch) | nl |  |
 |
 |
| Norsk bokmål (Norwegian Bokmål) | nb |  |
 |
|
| Polski (Polish) | pl |  |
qtbase_pl | |
| Português do Brazil (Brazil) | pt_BR |  |
qt_pt | |
| Português do Portugal (Portugal) | pt_PT |  |
qt_pt | |
| Русский (Russian) | ru |  |
 |
qtbase_ru |
| Suomi (Finnish) | fi |  |
 |
qtbase_fi |
| Svenska (Swedish) | sv |  |
 |
qt_sv |
| Українська (Ukrainian) | uk |  |
 |
qtbase_uk |
| 日本語 (Japanese) | ja |  |
qtbase_ja | |
| 中文 (Chinese) | zh_Hans_CN |  |
qt_zh_CN |
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 add suggestions which will eventually be accepted or rejected by registered users.
- You can easily register and login with your Github account. Registered users may set their language and subscribe for the OpenOrienteering project and for notifications. This needs to be done in the individual Weblate profile.
- Registered users can create and edit translations, and accept suggestions. Please pay attention to the comments, suggestions and checks for each item.
- Registered users may add new 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).
- 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.
OpenOrienteering uses Weblate's free hosting offer for open source projects. You may donate to Weblate to support both projects.
-
Placeholders: The source strings may contain placeholders such as
%1or%n.%1,%2etc. are replaced with some text or number when displayed. Since each number identifies a particular spot in the source string, you may change the order the placeholders so that it fits the grammar of the language you translate for.%nis a special marker which will be replaced with a number. In addition the value of the number is used to select between singular and plural versions of the translation. -
Shortcuts: An ampersand
&before a letter is used to mark the following letter as a shortcut key. In this case, the ampersand is not displayed, but usually the shortcut is indicated by underlining the letter. You may choose a different letter for the translation. -
HTML markup: Some strings contain HTML markup, such as
<b>...</b>for bold style. Please try to maintain this markup in the translation. -
Line breaks: Some strings contain line breaks in order to limit the width of some texts or to move certain parts of text to the beginning of a line. Please try to insert similar line breaks in the translation.
Attention: As long as Weblate produces quite different output than the Qt tools (https://github.com/WeblateOrg/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).
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 Qt's approach to writing source code for translation.
- Add
tr("....")to strings to be translated. In case of UTF-8 characters which are not part of the Latin-1 charset, usetrUtf8("...")instead. - For standard dialog box buttons, use
QDialogButtonBoxwith the appropriateStandardButtons. 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 (in addition to the context, 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_TRANSvariable 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), ormake Mapper_OpenOrienteering_template_update(for the template only). - Since weblate whitespace formatting differs from
lupdate/symbol_set_t, extra care should be taken not to merge pure whitespace changes. Updates can be committed to git with:
git diff -U0 -w --no-color | git apply --cached --ignore-whitespace --unidiff-zero -
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.