Internationalization

Loading locales

Default Location

By default, ActiveUI will look for translation files in the locales folder next to the index.html serving the application.

It is therefore your responsibility to provide up-to-date locales in such a folder. This can be achieved by, for example, using a Node.js postinstall script or copying those files manually (not recommended).

In the context of a Node.js project, there is a simpler way to load the translation files. Please checkout the ActiveUI application source code for an up-to-date example.

Custom Location

If the translation files are stored in another place, you can configure ActiveUI SDK to fetch them with a code such as:

const activeUI = createActiveUI({
  async fetchTranslation(locale, defaultFetchTranslation) {
    const response = await fetch(`https://my.app/locales/${locale}.json`);
    const translation = await response.json();
    // Translation can also be modified here if needed.
    return translation;
  },
});

Missing translations

The following type of warning might occur while running your application:

Error: Unresolvable path 'a.translation.path' in translation template

This means that the path a.translation.path is missing from the translations.

In that case, make sure that the translation files:

  • are correctly loaded.
  • are up to date with the version of ActiveUI SDK used.
  • contains all custom translations added in your project.

Creating a New Locale

Creating the translation file

New translation files should be located where ActiveUI SDK expects translations to be. See Loading locales for more information.

To create a new translation file such as pt-PT.json, copy an existing translation file like en-US.json and update all the values with the new translated equivalents.

  • Existing en-US.json

    {
  "...": "...",
  "popup": {
    "submit": "Submit",
    "cancel": "Cancel",
    "...": "..."
  }
}

  • New pt-PT.json

    {
  "...": "...",
  "popup": {
    "submit": "Enviar",
    "cancel": "Cancelar",
    "...": "..."
  }
}

Initialization

Setting the locale to be used on startup:

const activeUI = createActiveUI({
  defaultSettings: {'global.locale': 'pt-PT'},
});

Setting the list of available locales:

const activeUI = createActiveUI({
  supportedLocales: [
    {caption: 'English (US)', value: 'en-US'},
    {caption: 'Portugues', value: 'pt-PT'},
  ],
});

The locales that can be supported out of the box are en-US and fr-FR. If supportedLocales is not provided, then activeui-sdk will use the following:

[{caption: 'English', value: 'en-US'}, {caption: 'Français', value: 'fr-FR'}];

Altering Existing Translation Files

This code will add a new customTitle path and will edit an existing one at popup.close

const activeUI = createActiveUI({
  async fetchTranslation(locale, defaultFetchTranslation) {
    // Use the default behavior: fetching the translation file in the locales folder next to index.html.
    const translation = await defaultFetchTranslation();
    if (locale === 'fr-FR') {
      // add new key
      translation.customTitle = 'Traduction Personnalisée';
      // override an existing key
      translation.popup.close = 'Fermeture Personnalisée';
    } else {
      translation.customTitle = 'Custom Translation';
      translation.popup.close = 'Custom Close';
    }
    return translation;
  },
});

Creating an Internationalized Bookmark

It is possible to define translations for the name and description attributes of a bookmark.

Setup

To set up translations for a bookmark:

  1. Go to your content server UI page

  2. Under /ui/bookmarks/content/: find the ID of your bookmark (for example 2de).

  3. Under /ui/bookmarks/content/$bookmarkId: define the content of your bookmark, (name, description, value...). These will be the default values for the name and descriptions.

    {
  "description": "Default description",
  "name": "Alert List 311",
  "type": "container",
  "value": {
    "showTitleBar": false,
    "containerKey": "activemonitor-alert-list",
    "body": {
      "...": "..."
    }
  }
}

  4. For each locale name you want a translation for (en-US, fr-FR, etc...), define the name and the description to use for that locale. Example for adding French translations for a bookmark with ID 2de:

    Under /ui/bookmarks/i18n/fr-FR/2de:

    {
  "name": "Une super liste d'alertes!",
  "description": "Description française"
}

Current limitations

  • For dashboard bookmarks, only the main title and description of the bookmark can be translated, not the titles and descriptions of its inner widgets.
  • When a custom translation for a bookmark’s name or description exists, it is not possible to edit that field of that bookmark from ActiveUI. The name and description fields in the UI become disabled (greyed out), as we don’t want the user to edit one translation without editing the others.
← DeploymentMDX Manipulation →