Translation

Kai Pastor edited this page Nov 5, 2016 · 29 revisions

OpenOrienteering Mapper supports localization. This page gives an overview and hints to both translators and programmers.

Present state

Translation issues

Github: Open issues with label 'translations'
Weblate: Failing checks
Weblate: Source strings to check
Weblate: Ignored checks

Next release (Mapper 0.6.x) and unstable development snapshot

The user interface is translated to the following languages:

Language Code State
Čeština (Czech) cs Translation status
Dansk (Danish) da Translation status
Deutsch (German) de Translation status
English (plural forms only) en Translation status
Español de España (Spanish) es Translation status
Eesti (Estonian) et Translation status
Esperanto eo Translation status
Français (French) fr Translation status
עברית (Hebrew, right-to-left) he Translation status
Bahasa Indonesia (Indonesian) id Translation status
Italiano (Italian) it Translation status
Latviešu (Latvian) lv Translation status
Magyar (Hungarian) hu Translation status
Nederlands (Dutch) nl Translation status
Norsk bokmål (Norwegian Bokmål) nb Translation status
Polski (Polish) pl Translation status
Portuguêse do Brazil (Brazil) pt_BR Translation status
Русский (Russian) ru Translation status
Suomi (Finnish) fi Translation status
Svenska (Swedish) sv Translation status
Українська (Ukrainian) uk Translation status
日本語 (Japanese) ja Translation status
中文 (Chinese) cn Translation status

Information for Translators

Translation efforts should first focus on standard user interface items such as menu entries, window titles, button labels etc.

Translation online with Weblate

Translation status

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.

Special markers in translations

  • Placeholders: The source strings may contain placeholders such as %1 or %n. %1, %2 etc. 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. %n is 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.

New Languages

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.

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

Testing Translations

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

Translation Qt

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.
  • 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 (in addition to the context, supply a second parameter to tr(), e.g.
tr("m", "meters")

Maintaining Translations in the Build System

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

Merging translations

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.