13.3. Translations#

13.3.1. General#

The basic language of itom or its plugins is English. All strings in the source code should be written in English.

itom and its plugins can be translated to different other languages using the translation system of Qt.

The source translation strings of the core project of itom, its libraries (part of the itom SDK), designer plugins or plugins are stored in different ts files whose filename should follow the pattern: libraryname_langid.ts, where libraryname is a placeholder for the corresponding library or plugin and langid is a placeholder for the particular language.

The language can have the following format:

  • de for German

  • de_DE for German / Germany

  • de_CH for German / Switzerland

  • ko for Korean

For language codes (small letters) and / or country codes (capital letters) see https://docs.oracle.com/cd/E13214_01/wli/docs92/xref/xqisocodes.html.

Usually the source strings (in English) of the ts files are automatically created or updated by Qt’s tool lupdate. This tool parses all corresponding source files (h, cpp, ui), detects all translatable strings and updates the ts files.

The translations itself are then comfortabily done in the tool QtLinguist of Qt.

The ts files are then compiled using Qt’s lrelease tool into their binary representation qm. Each qm file has the same base filename than its original ts file and is put in several translation subfolders of the install or build folder of itom or its plugins subfolder. This qm-file compilation is automatically done during each build of the corresponding library.

For starting itom with another language, choose the desired language in the property dialog of itom. Possible languages depend on the available qm translation files:

13.3.2. Adding translations for the itom core project#

Adding new or existing translations for different languages to the itom core project or some of its plugins or designerplugins is usually done in the CMake configuration process.

Select the desired language codes (see above) as semicolon-separated string to the CMake variable ITOM_LANGUAGES. Since English is the default language, never add en to this string.

Example:

ITOM_LANGUAGES = de;fr
#this includes translations for German and French (in addition to English)

If you press Configure in CMake after having changed the ITOM_LANGUAGES variable, CMake checks if the corresponding ts files are available for all desired languages and all translatable libraries, that belong to the itom core project.

There is one common CMake error message, that might occur when setting new languages:

Error (ITOM_LANGUAGES = it):

CMake Error at cmake/ItomBuildMacros.cmake:664 (MESSAGE):
  Source translation file
  'C:/itom/sources/itom/Qitom/translation/qitom_it.ts' for language 'it is
  missing.  Please create this file first or set ITOM_UPDATE_TRANSLATIONS to
  ON
Call Stack (most recent call first):
  Qitom/CMakeLists.txt:759 (itom_library_translation)

CMake could not find the relevant Italian translation file qitom_it.ts. Since the additional CMake variable ITOM_UPDATE_TRANSLATIONS is likely to be set to OFF, itom is not allowed to automatically create an initial version of this file, such that the error is raised.

Solution: Set ITOM_UPDATE_TRANSLATIONS to ON if you add new languages. Then a bare version of a ts file is created for each non-existing language and Qt’s lupdate process is triggered when building each library. This also affects all existing ts file, such that they are also updated by new translatable strings in the source code.

Note

It is not recommended to manually create a new ts-file for a new language by copying an existing ts-file from another language, since each ts-file contains xml-content with the language ID as subcontent. If this language ID does not fit to the suffix of the filename, the lupdate process to update the translatable strings in this file will fail.

13.3.3. Updating or creating new ts-files#

Usually, the itom build process does not influence any ts-files during the build, hence, no-existing ts-files are not updated nor new ts-files for new languages in the CMake variable ITOM_LANGAUGES are created. However the binary compilation of qm-files from existing ts-files is always started when building the particular library.

The source translation update process can be triggered and controlled by the two boolean CMake variables ITOM_UPDATE_TRANSLATIONS and ITOM_UPDATE_TRANSLATIONS_REMOVE_UNUSED_STRINGS.

Set ITOM_UPDATE_TRANSLATIONS to force the itom (or plugins) build process to always update or create the ts-files for all desired languages (based on ITOM_LANGAUGES) using the tool lupdate of Qt. This is done by a special build project, whose name is equal to the corresponding library, followed by the suffix _translation (e.g. itomCommonQtLib_translation for the library itomCommonQtLib. The original library project depends on its _translation-project, such that this is always created before the library itself.

Usually, the lupdate tool parses all header, source and user-interface files of the library for translatable strings and adds them to the ts file, if they do not exist yet. However lupdate does not remove unused strings from the ts file. This can be changed by also setting ITOM_UPDATE_TRANSLATIONS_REMOVE_UNUSED_STRINGS to ON.

Please commit all changed ts files to the Git repository of the corresponding library (or plugin).

If ITOM_UPDATE_TRANSLATIONS is ON and a ts file has a wrong format, the following CMake error might occur:

CMake Warning at cmake/ItomBuildMacros.cmake:745 (message):
  - The existing ts-file
  C:/itom/sources/itom/AddInManager/translation/addinmanager_fr.ts does not
  contain the required language 'fr', but 'de'.  The lupdate process might
  fail.  Either fix the file or delete it and re-configure to let CMake
  rebuild an empty, proper ts file.
Call Stack (most recent call first):
  cmake/ItomBuildMacros.cmake:656 (itom_qt5_create_translation)
  AddInManager/CMakeLists.txt:96 (itom_library_translation)

In this case, the translation system expected a french translation file addinmanager_fr.ts, however the file was a copy from the german version addinmanager_de.ts, such that the internal xml content of the file was invalid. If this happens, lupdate will fail later. To fix this, remove the file and run CMake again or fix the content of the file.

13.3.4. Location of ts-files#

Usually the ts-files are always located in a translation subfolder of the sources of the wrapped library. These are for the itom core project:

  • sources/itom/AddInManager/translation

  • sources/itom/itomCommonQt/translation

  • sources/itom/itomWidgets/translation

  • sources/itom/plot/translation

  • sources/itom/shape/translation

  • sources/itom/qitom/translation

The translation files for plugins are always located in a subfolder translation of the particular plugin sources. The same holds for designerplugins.

When deploying itom, the qm-files are located in the following folders:

  • itom core project: itom-subfolder translation

  • designer plugins: itom-subfolder designer/translation

  • plugin (name: targetname): itom-subfolder plugins/<targetname>/translation

13.3.5. Translating plugins or designerplugins#

While the itom core project can directly be translated by setting the mentioned CMake variables ITOM_LANGUAGES, ITOM_UPDATE_TRANSLATIONS and optionally ITOM_UPDATE_TRANSLATIONS_REMOVE_UNUSED_STRINGS, some additional steps have to be done for translating plugins and / or designerplugins.

Besides configuring the mentioned CMake variables, you also have to set the following exemplary lines into the CMakeLists.txt file of the particular plugin:

#translation
set(FILES_TO_TRANSLATE ${PLUGIN_SOURCES} ${PLUGIN_HEADERS} ${PLUGIN_UI})
itom_library_translation(QM_FILES TARGET ${target_name} FILES_TO_TRANSLATE ${FILES_TO_TRANSLATE})

The FILES_TO_TRANSLATE list will contain all source (cpp), header (h) or user interface (ui) files, that should be parsed for new files. The translation project itself will be created by the itom macro itom_library_translation, provided by ItomBuildMacros.cmake. This will then create ts files in a translation subfolder of the plugin source folder whose particular names are targetname_langid.ts, where targetname corresponds to the project name of the plugin and langid is each language ID, contained in the semicolon-separated list ITOM_LANGUAGES.

On this page
Show Source