Localization in UIKit Web

UIKit Web has built-in support for localization (l10n) and internationalization (i18n).

Date and time

The timezone of the browser is automatically used for all dates and times and does not need to be configured.

Locales

The UIKit Web can be configured with locales. The locales provide translations for the UI using XLIFF translations and also handles date/time and additional representation using the standard ECMAScript Internationalization API which is supported by the major browsers.

By default, the UIKit Web is only configured with the default locale en. Any non-default locales must be configured in the Weavy Context. We provide a translation to Swedish sv-SE in the package, which you can use out-of-the box. Any additional locale resources can be easily generated from XLIFF using CLI tooling.

Configure locales

To be able to select a different locale than en, you must first provide the translation files and configure the available locales in the Weavy Context config. The provided sv-SE translation can be found in the uikit-web npm package at @weavy/uikit-web/dist/locales/sv-SE.js. Choose a publicly available place in your app to place a copy of this file, so that it will be accessible in the browser.

Next you need to configure the Weavy Context with the URL where to look for the translation files and configure which translations that are available. The default URL is ./locales.

When you have configured the locales, you will be able to specify one the locale to use; for instance sv-SE or en.

<wy-context locale="sv-SE" config='{ localesUrl: "./locales", locales: ["sv-SE"]}'></wy-context>
const weavy = new Weavy();

weavy.url = "https://myenvironment.weavy.io";
weavy.tokenUrl = "https://myserver.example/api/token";

weavy.localesUrl = "./locales",
weavy.locales = ["sv-SE"];

weavy.locale = "sv-SE";

Pre-loading translation files

By default, the translations are lazy-loaded. To speed up the loading of translation files you may pre-load the language file you are intending to use. We have built-in support for preloading language files using the recommended lit pre-loading methods. You can either provide static imports to provide instant translation or use dynamic imports to provide async preloading.

To provide pre-loaded localization templates, you need to populate the localizedTemplates property as a Map with optional static templates or async templates. You can mix these however you want. If the wanted locale isn't found, the template is loaded regularly using lazy-load.

We recommend providing the initially chosen locale as a static import to provide optimal loading of the initial locale without any glitches caused by async loading.

Static loading

The static loading guarantees that the locale is loaded and available when Weavy starts. This eliminates any async localization loading glitches that may appear in the UI. However, you should be restrictive about how much you load statically as this increases the size of your package. We recommend that you only load the initial locale statically.

import * as svSE from "@weavy/uikit-web/dist/locales/sv-SE.js";
import { Weavy } from "@weavy/uikit-web";

const weavy = new Weavy();

weavy.url = "https://myenvironment.weavy.io";
weavy.tokenUrl = "https://myserver.example/api/token";

weavy.locales = ["sv-SE"]

// Provide the content of the initially chosen svSE locale template
weavy.localizedTemplates = new Map([
  ["sv-SE", svSE]
]);

weavy.locale = "sv-SE";

Async pre-loading

The async loading starts when you start it in your code. This gives you dynamic control over the pre-loading. Weavy will await the async import() of locale template before applying it. Meanwhile, the rendering of the UI in Weavy continues with the default locale.

See: Dynamic import() on MDN

const weavy = new Weavy();

weavy.url = "https://myenvironment.weavy.io";
weavy.tokenUrl = "https://myserver.example/api/token";

weavy.locales = ["sv-SE"]

// Start pre-loading by dynamically importing an sv-SE locale template
weavy.localizedTemplates.set("sv-SE", import(`./locales/sv-SE.js`))

weavy.locale = "sv-SE";

HTML pre-loading

You can also provide pre-loading using only HTML. This works similar to the Async pre-loading and provides a dynamic way of preloading the locale templates using only HTML. We recommend only pre-loading the locale you intend to use initially.

<head>
  ...
  <link rel="modulepreload" href="./locales/sv-SE.js" />
</head>

Generating your own translations

You can generate any additional custom translation files and add them to your locale configuration. The locales should be named using BCP 47 language tag standard. The translation tool uses XLIFF 1.2 as interchange format for translations.

Install the lit localizer

To transform a XLIFF to a proper localization module for Weavy you need the Lit Localization tools.

npm install -D @lit/localize-tools

Once you have it installed you need to create a ./lit-localize.json configuration file to specify your locales, where your source files are and where you want the generated js modules should be placed.

Note: You must specify the path to the @weavy/uikit-web/tsconfig.json in the Weavy package, so that all translations can be verified by the tool.

Define which locales you want to generate using the targetLocales array. The sourceLocale must always be en.

Specify a folder for interchange.xliffDir where your source translations will be kept.

Specify a folder for output.outputDir where you want your generated modules to go. These may later require further processing by a web compiler.

You can choose whether you want to output js or ts for your build system.

lit-localize.json

{
    "$schema": "https://raw.githubusercontent.com/lit/lit/main/packages/localize-tools/config.schema.json",
    "tsConfig": "node_modules/@weavy/uikit-web/tsconfig.json",
    "sourceLocale": "en",
    "targetLocales": [
      "xx-pirate"
    ],
    "output": {
      "mode": "runtime",
      "language": "js",
      "outputDir": "./locales/"
    },
    "interchange": {
      "format": "xliff",
      "xliffDir": "./xliff/"
    }
  }

Extract translation strings

When you have the JSON configuration in place, you can extract all messages to XLIFF file. If you specified multiple locales, you will get multiple XLIFF files. Any existing XLIFF files will be updated with any new translation strings.

Use the lit-localize tool with the extract command.

npx lit-localize extract

Translate your file

Now that you have your XLIFF files ready for translation, you can translate manually or use any XLIFF editor you prefer. Save the translated XLIFF in the same place as it was.

To transform the XLIFF to js (or ts) you use the tool again with the build command.

npx lit-localize build

Process the generated js using any web compiler you like before serving it on the web.

Updating translations

Whenever you update @weavy/uikit-web you should repeat the commands to update your translations. Any new messages will be added to the XLIFF.

  1. Run the extract command.
  2. Update any translations in the XLIFF.
  3. Run the build command.
Weavy Docs