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 configured with the default locale en. 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 and can be configured for use in the Weavy Context.

<wy-context locale="sv-SE"></wy-context>

Configure locales

To be able to select a different locale than en or sv-SE, you must first provide the additional locale names and the translation modules. This is done with an array providing the files as javascript modules using the locales property in the Weavy Context config.

const weavy = new Weavy();

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

// Configure additional locales with lazy loading.
weavy.locales = [
  ["xx-pirate", () => import("./xx-pirate.js")]
];

// Select locale after configuring additional locales.
weavy.locale = "xx-pirate";

Pre-loading translation files

In the example above, the translations are lazy-loaded using a function with a dynamically loaded locale. To speed up the loading of translation files you may pre-load the language file you are intending to use. You can define locales using static (pre-built) loading, async loading or lazy loading.

To provide pre-loaded localization files, you need to populate the locales with the chosen methods for loading. You can mix these however you want.

We recommend providing the initially chosen locale as a static import to provide optimal 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";

// Provide the content of the initially chosen sv-SE locale template.
// Configure additional locales with async or lazy loading.
weavy.locales = [
  ["sv-SE", svSE], // Static locale, already loaded.
  ["es-ES", import("./es-ES.js")] // Async pre-loading, started instantly.
  ["xx-pirate", () => import("./xx-pirate.js")] // Lazy loading, when needed.
];

// Select locale after configuring additional locales.
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="https://myenvironment.weavy.io/uikit-web/es/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.

Run the extract command.
Update any translations in the XLIFF.
Run the build command.