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.

So it is your responsibility to provide up-to-date locales in the appropriate 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 explore the ActiveUI application source code to find 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 code similar to the following:

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 error message may 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.

If this happens, make sure that the translation files:

  • are correctly loaded.
  • are up to date with the version of ActiveUI SDK used.
  • contain 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 to find them. See Loading locales for more information.

To create a new translation file such as pt-PT.json, copy an existing translation file such as 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 that requires a translation (for example, 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 do not want the user to edit one translation without editing the others.

Configure Moment.js locale

Moment.js is used in particular by the Ant Design calendar component. If you are using the provided UMD bundle, Create React App or if you've configured your project following these guidelines, you might want to opt in specific Moment.js locales in your project. This can be done by directly declaring the imports in your project:

// load french locale
import from 'moment/locale/fr';
← DeploymentMDX Manipulation →