Localization is the process of supporting multiple languages and regions in your apps and components. Lit has first-party support for localization through the
@lit/localize library, which has a number of advantages that can make it a good choice over third-party localization libraries:
Native support for expressions and HTML markup inside localized templates. No need for a new syntax and interpolation runtime for variable substitution—just use the templates you already have.
Automatic re-rendering of Lit components when the locale switches.
InstallationPermalink to “Installation”
@lit/localize client library and the
@lit/localize-tools command-line interface.
Quick startPermalink to “Quick start”
- Wrap a string or template in the
- Create a
lit-localize.jsonconfig file (details).
lit-localize extractto generate an XLIFF file (details).
- Edit the generated XLIFF file to add a
<target>translation tag (details).
lit-localize buildto output a localized version of your strings and templates (details).
Making strings and templates localizablePermalink to “Making strings and templates localizable”
To make a string or Lit template localizable, wrap it in the
msg function. The
msg function returns a version of the given string or template in whichever locale is currently active.
Before you have any translations available,
msg simply returns the original string or template, so it's safe to use even if you're not yet ready to actually localize.
Message typesPermalink to “Message types”
Any string or template that you would normally render with Lit can be localized, including ones with dynamic expressions and HTML markup.
Plain string with expression (see strings with expressions for details on
HTML template with expression:
Localized messages can also be nested inside HTML templates:
Strings with expressionsPermalink to “Strings with expressions”
Strings that contain an expression must be tagged with either
str in order to be localizable. You should prefer
html when your string doesn't contain any HTML markup, because it has slightly less performance overhead. An error will be raised when you run the
lit-localize command if you forget the
str tag on a string with an expression.
str tag is required in these cases because untagged template string literals are evaluated to regular strings before they are received by the
msg function, which means dynamic expression values could not otherwise be captured and substituted into the localized versions of the string.
Locale codesPermalink to “Locale codes”
A locale code is a string that identifies a human language, and sometimes also includes a region, script, or other variation.
Lit Localize does not mandate use any particular system of locale codes, though it is strongly recommended to use the BCP 47 language tag standard. Some examples of BCP 47 language tags are:
- en: English
- es-419: Spanish spoken in Latin America
- zh-Hans: Chinese written in Simplified script
TermsPermalink to “Terms”
Lit Localize defines a few terms that refer to locale codes. These terms are used in this documentation, in the Lit Localize config file, and in the Lit Localize API:
- Source locale
The locale that is used to write strings and templates in your source code.
- Target locales
The locales that your strings and templates can be translated into.
- Active locale
The global locale that is currently being displayed.
Output modesPermalink to “Output modes”
Lit Localize supports two output modes:
Runtime mode uses Lit Localize's APIs to load localized messages at runtime.
Unsure which mode to use? Start with runtime mode. It's easy to switch modes later because the core
msg API is identical.
Runtime modePermalink to “Runtime mode”
Runtime mode makes switching locales very fast because a page reload is not required. However, there is a slight performance cost to rendering performance compared to transform mode.
Example generated outputPermalink to “Example generated output”
See the runtime mode page for full details about runtime mode.
Transform modePermalink to “Transform mode”
In transform mode, a separate folder is generated for each locale. Each folder contains a complete standalone build of your application in that locale, with
msg wrappers and all other Lit Localize runtime code completely removed.
Example generated outputPermalink to “Example generated output”
See the transform mode page for full details about transform mode.
DifferencesPermalink to “Differences”
|A dynamically loaded module for each target locale.
|A standalone app build for each locale.
|1.27 KiB (minified + compressed)
|Make template localizable
Config filePermalink to “Config file”
lit-localize command-line tool looks for a config file called
lit-localize.json in the current directory. Copy-paste the example below for a quick start, and see the CLI and config page for a full reference of all options.
inputFiles property to the location of your
.js source files. If you're writing TypeScript, set the
tsConfig property to the location of your
tsconfig.json file, and leave
Extracting messagesPermalink to “Extracting messages”
lit-localize extract to generate an XLIFF file for each target locale. XLIFF is an XML format supported by most localization tools and services. XLIFF files will be written to the directory specified by the
interchange.xliffDir config option.
For example, given the source:
<xliffDir>/<locale>.xlf file will be generated for each target locale:
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 your XLIFF files to your chosen translation service, you will eventually receive new XLIFF files in response. The new XLIFF files will look just like the ones you uploaded, but with
<target> tags inserted into each
When you receive new translation XLIFF files, save them to your configured
interchange.xliffDir directory, overwriting the original versions.
Building localized templatesPermalink to “Building localized templates”
lit-localize build command to incorporate translations back into your application. The behavior of this command depends on the output mode you have configured.
Message descriptionsPermalink to “Message descriptions”
desc option to the
msg function to provide human-readable descriptions for your strings and templates. These descriptions are shown to translators by most translation tools, and are highly recommended to help explain and contextualize the meaning of messages.
Descriptions are represented in XLIFF files using
Message IDsPermalink to “Message IDs”
Lit Localize automatically generates an ID for every
msg call using a hash of the string.
msg calls share the same ID, then they are treated as the same message, meaning they will be translated as a single unit and the same translations will be substituted in both places.
For example, these two
msg calls are in two different files, but since they have the same content they will be treated as one message:
ID generationPermalink to “ID generation”
The following content affects ID generation:
- String content
- HTML markup
- The position of expressions
- Whether the string is tagged with
The following content does not affect ID generation:
- The code inside an expression
- The computed value of an expression
- File location
For example, all of these messages share the same ID:
But this message has a different ID:
Note, while providing a description does not affect ID generation, multiple messages with the same ID but different description will produce an error during analysis to avoid ambiguity in the extracted translation unit. The following is considered invalid:
Make sure that all messages with the same ID also have the same description.
Overriding IDsPermalink to “Overriding IDs”
Message IDs can be overridden by specifying the
id option to the
msg function. In some cases this may be necessary, such as when an identical string has multiple meanings, because each might be written differently in another language: