Element Framework

i18n for App Developers

EF components support localization, including translated messages and formatting. In your app, setting the html lang attribute will trigger that language to be applied to relevant elements.

<html lang="ja">

Alternatively, setting the lang attribute directly on elements will have the same effect.

lang on an element supersedes the html lang, meaning multiple languages can exist on the same page.

Currently, the following languages are supported:

Language lang value
English (default) en
Japanese ja
German de
Simplified Chinese zh
Traditional Chinese zh-Hant

If an unsupported language is set, English is the default fallback.

Regionals

Adding region country codes will format all numbers and dates accordingly. For region specific languages to be applied, there must be additional region translations for that language.

If no country code is applied, the browser default is used.

Using in your app

EF elements are packaged with English translations only. The application developer must ensure that the additional languages are included, by importing any additional translation files.

The translation is selected using the following algorithm:

  • if the element has the lang attribute defined and a translation exists, select it, otherwise
  • if the html root element has the lang attribute defined and a translation exists, select it, otherwise
  • if a navigator.language translation exists, select it, otherwise
  • use the default English translation

There are many ways to load translations. Below are typical configurations, but it is up to the developer to pick the most appropriate solution.

Static Imports

The simplest way is to include translations in a bundle, for instance:

// # translations.js

// ef-tree-select, Japanese and German locales
import '@refinitiv-ui/phrasebook/lib/locale/ja/tree-select';
import '@refinitiv-ui/phrasebook/lib/locale/de/tree-select';

// ef-pagination, Simplified and Traditional Chinese locales
import '@refinitiv-ui/phrasebook/lib/locale/zh/pagination';
import '@refinitiv-ui/phrasebook/lib/locale/zh-hant/pagination';

Including translations in such a way will increase the bundle size, but has the benefit that translations are available immediately on application load.

Dynamic Import

If your application supports dynamic module resolution, you can load translations on demand. For instance:

import { supportedLocales } from '@formatjs/intl-utils';

// load language from your app's service
App.Settings.Language.read(value => {
  // set html lang tag
  document.documentElement.lang = value;
  // resolve regional locale into support locale.
  // for instance: if value === 'de-AT', then locale = 'de'
  const locale = supportedLocales(['ja', 'de'], [value])[0];
  if (locale) {
    // use dynamic import. Element will update itself once locale is loaded
    import(`@refinitiv-ui/phrasebook/lib/locale/${locale}/pagination`);
  }
});

From The Server

You can store translations as JSON on the app server or CDN. In this case you may want to extract JSON content to upload to the server.

import { supportedLocales } from '@formatjs/intl-utils';
import { Phrasebook } from '@refinitiv-ui/phrasebook';

// resolve locale from HTML lang attribute or navigator language
const locale = supportedLocales(['ja', 'de'], [document.documentElement.lang || navigator.language])[0];

// fetch locale
fetch(`static/locale/${locale}/pagination.json`).then(translations => {
  // define translation within Phrasebook to be available for EF elements
  Phrasebook.define('de', 'ef-pagination', translations);
});

Support IE11

IE11 lacks some features in the Intl object that are used in localization. You can choose how to address this, but the simplest appraoch is to install the @formatjs/intl-getcanonicallocales, @formatjs/intl-locale and @formatjs/intl-pluralrules polyfills and import them into your app. The polyfill is not included in EF by default, as not all apps support IE11.

npm install @formatjs/intl-getcanonicallocales @formatjs/intl-locale @formatjs/intl-pluralrules
// polyfills for IE11 for i18n
import '@formatjs/intl-getcanonicallocales/polyfill';
import '@formatjs/intl-locale/polyfill';
import '@formatjs/intl-pluralrules/polyfill';
import '@formatjs/intl-pluralrules/locale-data/en';
import '@formatjs/intl-pluralrules/locale-data/ja';
import '@formatjs/intl-pluralrules/locale-data/zh';

There are additional polyfills available for more advanced translation messages. You can get additional information at formatjs.io.