Default Gray Amethyst

Localization

Components can be localized by importing the appropriate translation file and setting the desired lang attribute on the <html> element. Here’s an example that renders Modes UI components in Spanish. 

<html lang="es">
  <head>
    <script type="module" src="/path/to/modes-web-components/dist/translations/es.js"></script>
  </head>

  <body>
    ...
  </body>
</html>

Through the magic of a mutation observer, changing the lang attribute will automatically update all localized components to use the new locale.

Available translations

Modes UI ships with a number of translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation. To see a list of all available translations in the latest version, refer to this directory.

The location of translations depends on how you’re consuming Modes UI.

  • If you’re using a bundler, import them from @metsooutotec/modes-web-components/dist/translations/[lang].js

You do not need to load translations up front. You can import them dynamically even after updating the lang attribute. Once a translation is registered, localized components will update automatically. 

// Same as setting <html lang="fi">
document.documentElement.lang = 'fi';

// Import the translation
import('/path/to/modes-web-components/dist/translations/fi.js');

Translation resolution

The locale set by <html lang="..."> is the default locale for the document. If a country code is provided, e.g. es-PE for Peruvian Spanish, the localization library will resolve it like this:

  1. Look for es-PE
  2. Look for es
  3. Fall back to en

Modes UI uses English as a fallback to provide a better experience than rendering nothing or throwing an error.

Multiple locales per page

You can use a different locale for an individual component by setting its lang attribute. Here’s a contrived example to demonstrate. 

<html lang="es">
  ...

  <body>
    <mo-button><!-- Spanish --></mo-button>
    <mo-button lang="ru"><!-- Russian --></mo-button>
  </body>
</html>

For performance reasons, the lang attribute must be on the component itself, not on an ancestor element. 

<html lang="es">
  ...

  <body>
    <div lang="ru">
      <mo-button><!-- still in Spanish --></mo-button>
    </div>
  </body>
</html>

This limitation exists because there’s no efficient way to determine the current locale of a given element in a DOM tree.

Creating your own translations

You can provide your own translations if you have specific needs or if you don’t want to wait for a translation to land upstream. The easiest way to do this is to copy src/translations/en.ts into your own project and translate the terms inside. When your translation is done, you can import it and use it just like a built-in translation.

Let’s create a Spanish translation as an example. The following assumes you’re using TypeScript, but you can also create translations with regular JavaScript. 

import { registerTranslation } from '@metsooutotec/modes-web-components/dist/utilities/localize';
import type { Translation } from '@metsooutotec/modes-web-components/dist/utilities/localize';

const translation: Translation = {
  $code: 'es',
  $name: 'Español',
  $dir: 'ltr',

  term1: '...',
  term2: '...',
  ...
};

registerTranslation(translation);

export default translation;

Once your translation has been compiled to JavaScript, import it and activate it like this.

<html lang="es">
  <head>
    <script type="module" src="/path/to/es.js"></script>
  </head>

  <body>
    ...
  </body>
</html>