Model localization

Localization is the process of translating user-facing applications into multiple languages.

When working on a model, designers define labels, descriptions, and other user-facing strings in order to provide a clear user experience. These strings are natively externalized in Semarchy xDM and can be translated (localized) to serve each user with the applications in his own language.

A user connecting an application created with Semarchy xDM sees these strings (label of the entities, attributes, list of values, etc.) translated in the language selected in his user profile, if such translation is available. Model localization consists in creating such translations.

If no translation is available for a given string in that language, the default string (for example, the label or description specified in the model) is used. This default string is the base translation.

Model localization only takes care of the strings defined in the model. Other built-in strings, common to all applications, such as 'My Tasks', 'Filter' or 'OK', can be localized using the platform-level Custom Translations.

Translation bundles

Strings translation is performed using Translation Bundles, attached to model editions.

A translation bundle is a properties file that contains a list of key/value pairs, corresponding to the strings localized in a given locale.
The translation bundle file is named translations_<locale>.properties, where <locale> is the locale of the translation.

The following example is a sample of a translation bundle file for the English language (translations_en.properties). In this file, the label for the Employee entity is the string Staff Member, and its description is A person who works for our company.

Example 1. translation_en.properties translation bundle sample

...
Entity.Employee.Label=Staff Member
Entity.Employee.Description=A person who works for our company.
Attribute.Employee.FirstName.Label=First Name
Attribute.Employee.FirstName.Description=First name of the employee
Attribute.Employee.Picture.Label=<New Key TODO>
...

Translate a model

To translate a model:

The translation bundles are exported for all the language(s) requiring translation in a single zip file.
Each translation bundle is translated by a translator using his translation tooling.
The translated bundles are re-imported into the model edition (either each file at a time or as a single zip file).

Make sure to translate all the strings of the model to avoid serving users with partially translated user interfaces.

Export translation bundles

To export translation bundles:

In the Management view, expand the Model Administration node, then expand the model and the model branch containing the edition that you want to localize.
Right-click and then select Export Translation Bundles…. The Export Translation Bundles wizard opens.
Select the languages you want to translate.
Select Export Base Bundle if you also want to export the base bundle for reference. The base bundle contains the default strings, and cannot be translated.
Select the Encoding for the exported bundles. Note that the encoding should be UTF-8 unless the language you want to translate or the translation tooling has other encoding requirements.
Select in Values to Export the export type:
- All exports all the keys with their current translated value. If a key is not translated yet, the value exported is the one specified by the Default Values option.
- New keys only exports only the keys not translated yet.
- All except removed keys exports all keys available, excluding those with no corresponding objects in the model. For example, the key for the description of an attribute that was deleted from a previous model edition will not be exported.
Select in Default Values the value to set for new keys (keys with no translation in the language).
- Use values for base bundle sets the value to the base bundle value.
- Use the defined tag sets the value to the tag specified in the field at the right of the selection (defaults to <New Key TODO>).
- Leave Empty set the value to an empty string.
Click OK to download the translation bundles in a zip format and then Close to close the wizard.

Import translation bundles

To import translation bundles:

In the Management view, expand the Model Administration node, then expand the model and the model branch containing the edition that you want to localize.
Right-click and then select Import Translation Bundles…. The Import Translation Bundles wizard opens.
Click the Browse button and select the translation file to import. This file should be either a properties file named translations_<locale>.properties or a zip file containing several of these properties files.
In the Language to Import table, select the language translations you want to import.
Select the Encoding for the import. Note that this encoding should correspond to the encoding of the properties files you import.
Select Cleanup Removed Keys During Import if you want to remove the translations for the keys that are no longer used in the model. This cleanup removes translations no longer used by the model.
Click Finish to run the import.

The translations for the model edition in the selected languages are updated with those contained in the translation bundles. If the Cleanup Removed Keys During Import was selected, translations in these languages no longer used in the model are removed.

Translation and model edition life cycles

The life cycle of the translations is entirely decoupled from the model edition and deployment life cycle:

It is possible to modify the translations of open or closed model editions, including deployed model editions in production data locations.
Translation changes on deployed model editions are taken into account dynamically when a user accesses an application defined in this model edition.

Decoupling the translation life cycle from the model edition avoids binding the critical model development and release process to the translation process, as the latter frequently is managed by a separate team. This also allows adding new translations or fixing translations without having to re-deploy a new model edition.

When creating a new model edition, the translations from the previous model edition are not copied to the next edition. It is necessary to export and import translations between editions.