Skip to main content

Localization

Lit localize is a Labs feature. It's ready to use, but is still in active development, so some additional features may be missing. Check the open issues for details.

Lit includes powerful support for localization/internationalization through the @lit/localize package. Localization refers to the process of supporting multiple languages and locales in your apps and components. @lit/localize allows you to:

  • Embed HTML markup and data expressions in your localized templates using natural Lit syntax, just by wrapping your templates in the msg function.

  • Extract messages to standard XLIFF format for integration with all major translation services.

  • In transform mode, generate a zero-overhead bundle for each locale, where all msg calls are replaced by localized templates that render as fast as possible.

  • In runtime mode, automatically re-render your app whenever the locale changes, just by adding the @localized decorator to your components.

Install the @lit/localize client library and the @lit/localize-tools command-line interface.

Wrapping a Lit template with the msg() function allows @lit/localize-tools to extract it so that it can be sent for localization, and to replace it with the localized version once available.

Before you have any translations available, msg() simply returns the unmodified template, so it's safe to start using even if you're not yet ready for localization.

@lit/localize supports two build modes: transform and runtime, each with their own advantages. It's easy to switch between the two, because the core msg API is identical.

In transform mode, Lit generates a separate folder for each locale. Each folder contains a complete standalone build of your application in that locale, with msg wrappers completely removed.

Transform mode has zero runtime overhead, so it is extremely fast to render. However, switching locales requires re-loading your application with a different JS bundle.

Sample output

In runtime mode, Lit generates one JS module for each of your locales, containing the localized templates for that locale.

When your application switches locales, Lit imports the new template module, and re-renders. Runtime mode makes switching locales very fast, but rendering suffers a performance penalty compared to transform mode.

Sample output

To start handling translations, create a JSON file called lit-localize.json in your project's root directory.

sourceLocale
string

Required locale code that templates in the source code are written in.

targetLocales
string[]

Required locale codes that templates will be localized to.

tsConfig
string

Path to a tsconfig.json file that describes the TypeScript source files from which messages will be extracted.

output.mode
"transform" | "runtime"

What kind of output should be produced. See modes.

output.localeCodesModule
string

Optional filepath for a generated TypeScript module that exports sourceLocale, targetLocales, and allLocales using the locale codes from your config file. Use to keep your config file and client config in sync.

interchange.format
"xliff" | "xlb"

Data format to be consumed by your localization process. Options:

  • "xliff": XLIFF 1.2 XML format
  • "xlb": Google-internal XML format

output.outputDir
string

Transform mode only

Output directory for generated TypeScript modules. Into this directory will be generated a <locale>.ts for each targetLocale, each a TypeScript module that exports the translations in that locale keyed by message ID.

interchange.xliffDir
string

XLIFF only

Directory on disk to read/write .xlf XML files. For each target locale, the path "<xliffDir>/<locale>.xlf" will be used.

Run lit-localize extract command to generate an XLIFF file for each target locale. XLIFF is an XML format supported by many localization tools and services. XLIFF files will be written to the directory specified by the interchange.xliffDir config option.

XLIFF files can be edited manually, but more typically they are sent to a third-party translation service, where they are edited by language experts using specialized tools.

After uploading an XLIFF file to your chosen translation service, you will eventually receive a new XLIFF file in response. The new XLIFF file will look just like the one you uploaded, but with <target> tags inserted into each <trans-unit>.

When you receive a new translation XLIFF file, save it to your xliff/ directory, overwriting your original version.

Use the lit-localize build command to incorporate translations back into your application. The behavior of this command depends on the mode you have configured.

When using runtime mode, you can switch locales dynamically, without a page reload.

Note that in transform mode, switching locales requires re-loading your application with a different client bundle. The remainder of this section applies to runtime mode only.

To automatically trigger a re-render when the locale changes, apply the @localized decorator to your class, or call the updateWhenLocaleChanges function in your constructor.

To trigger a locale switch, you must first initialize the Lit localization client library using configureLocalization. This tells Lit which locale modules are available and how to load them, and returns a setLocale function.

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

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, as in the example below).

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

Use the desc option to provide human-readable descriptions for your localized Lit templates. These descriptions are shown to translators, and are highly recommended to help explain and contextualize the meaning of messages.

Every message needs a unique ID so that it can be tracked through the translation process.

Message IDs are generated automatically based on a hash of the template contents. All parts of a template affect the automatic ID, except for the contents of expressions (though the position of expressions does affect the ID).

Lit splits your localizable templates into two categories: localizable parts and placeholder parts. Placeholders are visible to translators, and can be repositioned within the template, but their contents cannot be changed.

  • Localizable: Hello
  • Placeholder: <b>${user}</b>
  • Localizable: !

For example, in right-to-left scripts such as Arabic and Hebrew, placeholders will typically move positions: