Clone this wiki locally
OpenOrienteering Mapper supports localization. This page gives an overview and hints to both translators and programmers.
Next release (Mapper 0.6.x) and unstable development snapshot
The user interface is translated to the following languages:
Information for Translators
Translation efforts should first focus on standard user interface items such as menu entries, window titles, button labels etc.
- 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.
Special markers in translations
Placeholders: The source strings may contain placeholders such as
%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.
Translation offline with Qt Linguist
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 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
Information for Programmers
- Learn about the Qt translation framework from a programmer's point of view.
tr("....")to strings to be translated. In case of UTF-8 characters which are not part of the Latin-1 charset, use
- For standard dialog box buttons, use
QDialogButtonBoxwith 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 (in addition to the context, supply a second parameter to
Maintaining Translations in the Build System
- 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), 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.