Skip to main content

Runtime localization mode

In Lit Localize runtime mode, one JavaScript or TypeScript module is generated for each of your locales. Each generated module contains the localized templates for that locale. When your application switches locales, the module for that locale is imported, and all components are re-rendered.

See output modes for a comparison of Lit Localize output modes.

Example output

The following example demonstrates an application built with Lit Localize runtime mode:

The Lit GitHub repo includes full working examples (JavaScript, TypeScript) of Lit Localize runtime mode that you can use as templates.

In your lit-localize.json config, set the mode property to runtime, and set the output.outputDir property to the location where you would like your localized template modules to be generated. See runtime mode settings for more details.

In your JavaScript or TypeScript project, call configureLocalization function, passing an object with the following properties:

  • sourceLocale: string: Required locale code in which source templates in this project are written, and the initial active locale.

  • targetLocales: string[]: Required locale codes that are supported by this project. Should not include the sourceLocale code.

  • loadLocale: (locale: string) => Promise<LocaleModule>: Required function that returns a promise of the localized templates for the given locale code.

Use the output.localeCodesModule setting to generate a module which exports a sourceLocale string and targetLocales array that can be passed to configureLocalization, to ensure that your runtime code remains in sync with your config file.

configureLocalization returns an object with the following properties:

The getLocale function returns the active locale code. If a new locale has started loading, getLocale will continue to return the previous locale code until the new one has finished loading.

The setLocale function begins switching the active locale to the given code, and returns a promise that resolves when the new locale has loaded.

To automatically trigger a re-render of your component each time the active locale switches, apply the updateWhenLocaleChanges function in your constructor when writing JavaScript, or apply the @localized decorator to your class when writing TypeScript.

The lit-localize-status event fires on window whenever a locale switch starts, finishes, or fails. You can use this event to:

  • Re-render when you can't use the @localized decorator (e.g. when using the Lit render function directly).

  • Render as soon as a locale switch begins, even before it finishes loading (e.g. a loading indicator).

  • Perform other localization related tasks (e.g. setting a locale preference cookie).

The detail.status string property tells you what kind of status change has occured, and can be either loading, ready, or error:

loading

A new locale has started to load.

The detail object contains:

  • loadingLocale: string: Code of the locale that has started loading.

In the case that a second locale is requested before the first one finishes loading, a new loading event is dispatched, and no ready or error event will be dispatched for the first request.

A loading status can be followed by a ready, error, or loading status.

ready

A new locale has successfully loaded and is ready for rendering.

The detail object contains:

  • readyLocale: string: Code of the locale that has successfully loaded.

A ready status can be followed only by a loading status.

error

A new locale failed to load.

The detail object contains:

  • errorLocale: string: Code of the locale that failed to load.
  • errorMessage: string: Error message from locale load failure.

An error status can be followed only by a loading status.

Lit Localize lets you load locale modules however you like, because you can pass any function as the loadLocale option. Here are a few common patterns:

Use dynamic imports to load each locale only when it becomes active. This is a good default because it minimizes the amount of code that your users will download and execute.

Start pre-loading all locales when the page loads. Dynamic imports are still used to ensure that the remaining script on the page is not blocked while the locale modules are being fetched.

Use static imports to pre-load all locales in a way that blocks other script on the page.

This approach is not usually recommended because it will cause more code than necessary to be fetched and executed before the rest of the script on the page can execute, blocking interactivity. Use this approach only if your application is extremely small, must be distributed in a single JavaScript file, or you have some other restriction that prevents the use of dynamic imports.