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
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
msgcalls 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
@localizeddecorator to your components.
ExamplePermalink to Example
InstallationPermalink to Installation
@lit/localize client library and the
@lit/localize-tools command-line interface.
Making templates localizablePermalink to Making templates localizable
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.
Build output modesPermalink to Build output modes
@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.
Transform modePermalink to Transform mode
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.
Runtime modePermalink to Runtime mode
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.
Config filePermalink to Config file
To start handling translations, create a JSON file called
lit-localize.json in your project's root directory.
Config optionsPermalink to Config options
Required locale code that templates in the source code are written in.
Required locale codes that templates will be localized to.
Path to a
tsconfig.jsonfile that describes the TypeScript source files from which messages will be extracted.
"transform" | "runtime"
What kind of output should be produced. See modes.
Optional filepath for a generated TypeScript module that exports
allLocalesusing the locale codes from your config file. Use to keep your config file and client config in sync.
"xliff" | "xlb"
Data format to be consumed by your localization process. Options:
"xliff": XLIFF 1.2 XML format
"xlb": Google-internal XML format
Transform mode only
Output directory for generated TypeScript modules. Into this directory will be generated a
targetLocale, each a TypeScript module that exports the translations in that locale keyed by message ID.
Directory on disk to read/write
.xlfXML files. For each target locale, the path
"<xliffDir>/<locale>.xlf"will be used.
Extracting messagesPermalink to Extracting messages
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.
Translation with XLIFFPermalink to Translation with XLIFF
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
When you receive a new translation XLIFF file, save it to your
xliff/ directory, overwriting your original version.
Building a localized appPermalink to Building a localized app
lit-localize build command to incorporate translations back into your application. The behavior of this command depends on the mode you have configured.
Switching localesPermalink to Switching locales
When using runtime mode, you can switch locales dynamically, without a page reload.
Localized decoratorPermalink to Localized decorator
@localized decorator to your
LitElement components to automatically trigger a re-render whenever the locale changes.
configureLocalizationPermalink to configureLocalization
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
setLocalePermalink to setLocale
setLocale function begins switching the active locale to the given code, and returns a promise that resolves when the new locale has loaded.
lit-localize-status eventPermalink to lit-localize-status event
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
@localizeddecorator (e.g. when using the Lit
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).
Message descriptionsPermalink to Message descriptions
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.
Message IDsPermalink to Message IDs
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).
Message placeholdersPermalink to Message placeholders
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.
For example, in right-to-left scripts such as Arabic and Hebrew, placeholders will typically move positions: