Multi-source Development and Version Control

Working with translation files in environments where multiple developers contribute to the same project requires a consistent configuration and a defined workflow for merging and version control.

Prerequisites

To ensure a proper multi-source development workflow with the Translator, all developers must fulfill the following requirements:

  • All developers must use the same paramLang setting. If the paramLang differs between developers, the order of entries in the generated .ts files may differ, making file comparison and merging impossible.
  • The [general] translationSourceLang config entry should be set explicitly for sub-projects to avoid ambiguous source language resolution.

Translation Source Language Resolution

The Translator determines the source language for translation file generation as follows:

  • In the project: The paramLang config entry is used.
  • In sub-projects: The translationSourceLang config entry is searched in the config.level. If not defined, the behavior depends on the location:
    • Below the WinCC OA installation directory (e.g., an installed add-on): en_US.utf8 is used as the default language.
    • In other directories: For each panel file, the first LangText object is evaluated. If en_US.utf8 is present, it is used; otherwise, the first language of the file is used.

Merging Translation Files

The translation source files (.ts) are XML-based. This means they can be merged with standard text-based merge tools. Since the .ts files are normally extended (new entries are added at the end), parallel work on the same sub-project typically results in clean text merges.

Important:
The compiled .qm files are binary and cannot be merged. They must be regenerated after merging the .ts source files.

The recommended workflow for merging translations in a multi-source environment:

  1. Ensure all developers use the same paramLang configuration.
  2. Generate or update the .ts translation files via the Translator Panel.
  3. Merge the .ts files using your version control system's standard text merge functionality.
  4. After merging, regenerate the .qm files by clicking Create .qm Files in the Translator panel.

Format Conversion

Translation files can be converted between the Qt .ts format and the XLIFF format (.xlf) using the lconvert command-line tool provided with the Qt installation. This is useful when translation work is performed with external tools that support XLIFF but not the Qt .ts format.

Convert a .ts file to XLIFF:

lconvert -i project_de.ts -o project_de.xlf

Convert an XLIFF file back to .ts format:

lconvert -i project_de.xlf -o project_de.ts
Note:
The lconvert tool is located in the Qt bin directory within the WinCC OA installation. XLIFF versions 1.1 and 1.2 are supported.

After converting back to .ts format, regenerate the .qm file to apply the translations at runtime.

Working with Git

When using git for version control of translation files, observe the following best practices:

  • Commit .ts files to the repository. These are the editable source files for translations and can be merged as text.
  • Regenerate .qm files before committing. Since .qm files are binary, they cannot be merged. Always run Create .qm Files (or lrelease from the command line) before committing to ensure the binary files match the current .ts source.
  • Resolve .ts merge conflicts manually. If multiple developers modify the same .ts file concurrently, merge conflicts may occur in the XML structure. Resolve them with a text editor or merge tool, ensuring the XML remains well-formed.
  • Consider branch workflows. When merging translation files between branches (e.g., support branches), merge the .ts files first and then regenerate the .qm files on the target branch.
Note:
The more developers work on the same translation file concurrently, the higher the probability of merge conflicts. For large teams, consider dividing translation work by sub-project to minimize conflicts.