Localization

pSeven Enterprise supports UI localization, which allows you to translate its UI into your local language, as well as to provide users with a multilingual UI by adding more translations.

To add a UI language, you need to upload a set of translation files to the pSeven Enterprise shared data storage. For users, the language switch is automatic: pSeven Enterprise detects the language from browser settings (1) and displays UI in that language, if you have uploaded the needed translation files. If they are missing, the UI falls back to English.

1. To detect language, pSeven Enterprise checks the Accept-Language HTTP header sent by the user's browser and picks the first language from the list in this header. The order of that list is the order of the user's preferred languages as set in their browser. Usually, the first language there is the same as the OS interface language. Most users never change this default; in many browsers, this setting is even hidden from users.

You can add or update translation files at any time, without stopping pSeven Enterprise. This doesn't interrupt users.

For quality localization, translators need access to the pSeven Enterprise UI and need to be able to upload translation files themselves, so they can test translations directly in the UI. It's advisable to create a separate pSeven Enterprise Express deployment for translators. It can be set up with minimal resources since translators don't need to run production workflows and other resource-intensive tasks.

Adding languages

Localization files - sources in English and translations - are stored inside the localization and protoblocks folders in the pSeven Enterprise shared data storage ({shared data}).

To add a language, send the source files to translators, receive the translated files from them, and upload those files to the shared data storage. Names of localization files and folders use the ISO 639-1 two-letter language codes. For instance: en.json for English (source), zh.json for Chinese, fr.json for French.

Shared data storage location

In pSeven Enterprise Express, {shared data} is a folder in the VM filesystem. It has a fixed path: /Storage/pSeven/Shared.

In a Kubernetes deployment, {shared data} is a folder on the NFS server, specified by storage.shareddata.nfs.path in values.yaml. You can use helm get values to check the values in your deployment; usually:

helm get values pseven-rl -n pseven-ns -o yaml > values.txt

You can also use exportfs -av on the NFS server to check the paths to exported directories, for instance:

$ exportfs -av
exporting *:/var/pSeven/SharedData
exporting *:/var/pSeven/WorkspaceData
exporting *:/var/pSeven/UserData

When you install pSeven Enterprise, it writes the English language files to {shared data}/localization/ and {shared data}/protoblocks/. These files are the translation sources.

The {shared data}/localization/ folder contains the common localization files:

• en.json - common UI texts: panes, dialogs, buttons
• locale/en/LC_MESSAGES/django.po - common log messages

The {shared data}/protoblocks/ folder contains block localization files ({version} is the block's version number):

• App reference: appreference-e34d02547f8e11f09ddce37c62c4fb04-{version}/locales/en.json
• Condition: condition-5e93728d8bc9421e9d739643e512c327-{version}/ui/locales/en.json
• Model builder: modelbuilder-57e3ba1a234811e298c5e0699576c43b-{version}/frontend/locales/en.json
• Uncertainty quantification: uq-696df2064c824422a7c164d7fa746388-{version}/frontend/locales/en.json
• While: while-0a8085253a7c4806b3f9cb5f0e1143f5-{version}/frontend/locales/en.json

Outdated block versions don't support localization

pSeven Enterprise also keeps outdated block versions in {shared data}/protoblocks/ to maintain compatibility with user workflows created earlier. In those outdated versions, the support for localization might be missing. If you can't find the locales folder in a certain block version, it means that localization is unsupported.

The language files use common formats supported by the majority of computer aided translation (CAT) tools for import and export: en.json files are simple key-value JSONs, django.po is a gettext file.

Translators must maintain the same file formats in the translation files. Copy the common translation files to localization/{lang}.json and localization/locale/{lang}/LC_MESSAGES/django.po; copy the block translation files named {lang}.json to their respective folders inside protoblocks. In file names and paths, {lang} is the ISO 639-1 two-letter language code. For instance, Chinese translation files would be:

• localization/zh.json - common UI texts,
• localization/locale/zh/LC_MESSAGES/django.po - common messages,
• appreference-e34d02547f8e11f09ddce37c62c4fb04-{version}/locales/zh.json - App reference block UI and messages,
• condition-5e93728d8bc9421e9d739643e512c327-{version}/ui/locales/zh.json - Condition block UI and messages, and so on.

For blocks, you will also need to copy certain translated strings (1) from translation files to block manifests. For each block:

1. block's group name for the Block library pane, block description, and its port descriptions

1. In the block folder in {shared data}/protoblocks, find the manifest.yaml file.
2. In the block translation file ({lang}.json), find the keys prefixed [manifest.yaml]. There, the key name is the full name of the manifest parameter to which you should add the translation.

3. Copy the translated strings from {lang}.json and add them to parameter values in the manifest. Extend the existing values, do not replace.

   Localized parameters are marked with this comment: #Add translations here.

The values of parameters you have to edit are localized strings - collections where keys are two-letter language codes, and values are translated strings. When editing them, extend the collections with new key-value pairs for your language; do not remove nor edit the English string values under the "" keys. (1)

1. for instance, "": "Input signal port."

English sourceGerman translationFrench translationLocalized block

en.json

{
    "[manifest.yaml] default_preset.template.description": "Test block.",
    "[manifest.yaml] default_preset.template.inputs.acd9a4d00b954f8694378d9c246e2afc.description": "Input signal port.",
    "[manifest.yaml] groups[0]": "General"
}

de.json

{
    "[manifest.yaml] default_preset.template.description": "Testblock.",
    "[manifest.yaml] default_preset.template.inputs.acd9a4d00b954f8694378d9c246e2afc.description": "Eingabesignal-port.",
    "[manifest.yaml] groups[0]": "Universal"

}

fr.json

{
    "[manifest.yaml] default_preset.template.description": "Bloc de test.",
    "[manifest.yaml] default_preset.template.inputs.acd9a4d00b954f8694378d9c246e2afc.description": "Port de signal d'entrée.",
    "[manifest.yaml] groups[0]": "Universels"
}

manifest.yaml

groups:
    -
        "": "General"
        "de": "Universal"
        "fr": "Universels"
default_preset:
    template:
        description:
            "": "Test block."
            "de": "Testblock."
            "fr": "Bloc de test."
        inputs:
            acd9a4d00b954f8694378d9c246e2afc:
                name: "@go"
                description:
                    "": "Input signal port."
                    "de": "Eingabesignal-port."
                    "fr": "Port de signal d'entrée."

To test a translation, change your system UI language to the one you're testing, or set it as the most preferred language in your browser. Sign in to pSeven Enterprise as a user; the UI should switch to the new language automatically. The translated UI texts are updated instantly, and the update of translated messages usually takes a few minutes.

If you see the default English UI after the sign-in, check the Accept-Language headers sent by your browser. The language you're testing should be the first in the list in these headers. The language code in the header must comply with ISO 639; however, it doesn't have to be a two-letter code - for example, Chinese can be specified as zh, zh-CN, or zh-HK.

Updating translations

The localization sources get updated with every pSeven Enterprise release. When you upgrade to a new version, its updated English language files are installed to {shared data}/localization/ and, if that version updates any blocks, to {shared data}/protoblocks/. The update maintains compatibility with translation memory (TM) in CAT tools: adds new and updated translation segments (keys), preserves existing segments that didn't change.

To update a localization, send the new versions of the English sources to translators, receive the updated translation files, and upload them to {shared data}:

• In localization, replace the existing translation files with the new ones.
• In protoblocks, upload the new translation files to the block folders with the highest version number.

Translations can be updated at any time: this doesn't require stopping pSeven Enterprise and doesn't interfere with users.

The {shared data}/localization/ folder stores backup copies of the English source files from previously installed versions, created during version upgrades. After an upgrade, you may delete these backups if necessary.

Do not delete translation files from block folders. Each block version is localized independently, so existing localization files in outdated block versions are required.

Sign-in page localization

The user sign-in page is part of the built-in authentication service, Keycloak. It uses Keycloak's built-in localization, which is configured separately.

1. Sign in to Keycloak as an administrator.
2. Open settings and go to the Realm settings section.
3. On the Localization tab, enable Internationalization.
4. Select the languages you need from Supported locales and save your settings.