Manage custom translations

Custom translations let you localize and override built-in strings that appear in the Semarchy xDM user interfaces.

Semarchy xDM allows translating the strings you define in applications (e.g., the labels of business views or fields) as part of the model and application localization effort.

In addition, strings that are built in Semarchy and that are visible in all data management and dashboard applications—​such as 'My Tasks', 'Filter' or 'Global Search'--can also be modified in the platform configuration with custom translations.

With custom translations, you can:

  • Override existing built-in strings. For example, replace "My Tasks" with "All Tasks" in the My Tasks editor title.

  • Create translations for new languages for the built-in strings.

Custom translations are configured at the platform level and apply to all the applications served by the platform.
Model- or application-specific translations are managed in the model lifecycle. For more information, see Model localization.

The translation process consists of:

  1. Exporting existing languages' localization files, or blank localization files for new languages. These files are properties files, which can be modified using a text editor.

  2. Editing these files using a text editor.

  3. Import the modified files.

Export custom translations

To export custom translations:

  1. In the navigation drawer of the Configuration module, select Custom Translations.
    The Custom Translations editor opens and lists the custom translations that you have configured.

  2. To modify existing custom translations, select these translations in the list.

  3. Click the export Export Translations…​ button in the editor toolbar.

  4. In the Export Translation Bundles dialog, select the translation bundles that you want to export. The Hide Languages with no Custom Translations option masks the languages for which you have no custom translation.

  5. Click OK
    The selected translation bundles are exported in a zip file.

Export file format

Export file organization

Translations are exported as a compressed file that contains properties files (containing key=value pairs).

These files are organized into folders:

  • The /commons folder contains properties files for all the languages with strings common to the dashboard and data management applications.

  • The /dashboards folder contains properties files for all the languages with strings specific to the Semarchy xDM Dashboard component.

  • The /discovery folder contains properties files for all the languages with strings specific to the xDM Discovery component.

  • The /applications folder contains the properties files for all the languages with strings specific to the data management applications.

After editing the custom translation properties files, make sure to compress these files into a zip file that follows the exact same structure, as it is expected by the import process. The folders listed above must be at the root of the compressed file. Make sure to compress these folders directly and not their parent folder.

Translation properties files

Custom translation properties files are exported with UTF-8 encoding. You should preserve this encoding when editing the translations.

Note that:

  • You can use the \uXXXX notation for special characters.

  • Leading spaces are automatically removed from the translations.

  • Empty translations are ignored.

  • To replace an existing translation with a blank one, you must use a space character—​using the \u0020 notation—​for the translation.

Languages and variants

Properties files have a suffix corresponding to the language code and an optional variant code.

Example of language and variant

The en suffix stands for the generic English language, and en_US stands for the United States variant of this language. When a key needs to be translated:

  • Users configured to use a specific variant (e.g., en_US) will use that specific variant translation if it is available, or revert to the generic (e.g., en) translation.

  • Users configured to use the generic language (e.g., en) will directly use that translation.

In addition, specific properties files with the en_default and en_default suffixes represent the default translations built-in Semarchy xDM for English and French. These are here for informational purposes and are ignored during the import process.

Language translation fallback

The localization mechanism uses a fallback process to translate localization keys into translated strings.

In this process, keys translate into localized strings using the available translations, in the following order:

  1. The language variant custom translation (e.g., fr_FR).

  2. The generic language custom translation (e.g., fr).

  3. The generic language built-in translation. Semarchy xDM includes such translations for English and French.

  4. The built-in default translation. This translation uses the English language.

Using the fallback mechanism, you can define overrides on top of the built-in translations.
For example, to fix a single string in the UI for English-speaking users, you must provide a custom translation for the English language that only contains that string. The rest of the strings, via the fallback process, will be using the English built-in translations.

Import custom translations

To import custom translations:

  1. In the navigation drawer of the Configuration module, select Custom Translations.
    The Custom Translations editor opens.

  2. Click on the import Import Translations…​ button in the editor toolbar.

  3. Click the Browse button and select a zip file containing custom translations.
    The editor shows in the Languages to import the custom translations available in the file.

  4. Select the properties files that you want to import, and then click Finish
    The selected translation bundles are imported.

When importing a custom translation for a language that is not translated yet, a new translation is created. If a custom translation already exists for a given language, it is removed and replaced entirely by the new one.

After importing or modifying a custom translation, users must refresh the applications to see the new translation.