Learn
Localization

Localizing the UIKit

The Weavy UIKit has built-in support for localization (l10n) and internationalization (i18n) by importing the appropriate translation files and setting the locale property. The timezone of the browser is automatically used for all dates and times and does not need to be configured.

Configuration

By default, the UIKit is configured to use English (en) which also serves as the fallback locale. We also provide a translation to Swedish that you can use out-of-the box by setting the locale property to sv-SE. Additional locales are supported by providing translations using XLIFF files.

Providing translations

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

const weavy = new Weavy();
weavy.url = "{WEAVY-URL}";
weavy.tokenUrl = "https://example.com/myapp/token";

// Configure available locales
weavy.locales = [
  ["xx-pirate", () => import("./xx-pirate.js")]
];

// Set locale
weavy.locale = "xx-pirate";

In the example above, the translation file is lazy-loaded, but you can also configure translation files using static or async loading.

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

const weavy = new Weavy();
weavy.url = "{WEAVY-URL}";
weavy.tokenUrl = "https://example.com/myapp/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.
];

// Set locale after configuring locales.
weavy.locale = "sv-SE";

You can also load translation files using only HTML. This works similar to the async pre-loading.

<head>
  ...
  <link rel="modulepreload" href="{WEAVY-URL}/uikit-web/es/locales/sv-SE.js" />
</head>

Static loading guarantees that the locale is loaded and available when Weavy starts. This eliminates any async localization 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.

Generating translations

You can provide additional translations by generating translation files and adding them to your locales configuration.

Install and configure tools

To generate localization files for Weavy you need to install the Lit localize tools.

npm install -D @lit/localize-tools

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

First, you must set the tsConfig path to the @weavy/uikit-web/tsconfig.json in the Weavy package, so that all translations can be verified by the tool.
Define the locales you want to generate using the targetLocales array. The locales should be named using BCP 47 language tag standard. 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.
With output.language you can choose whether you want to output js or ts for your build system.

Example: 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 files. 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 them manually or use any XLIFF editor you prefer. Save the translated XLIFF in the same place as it was.

To transform the translated XLIFF file 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.