Runtime localization mode
See output modes for a comparison of Lit Localize output modes.
Example of using runtime modePermalink to “Example of using runtime mode”
The following example demonstrates an application built with Lit Localize runtime mode:
Configuring runtime modePermalink to “Configuring runtime mode”
lit-localize.json config, set the
output.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.
output.localeCodesModule to a filepath of your chosing. Lit Localize will generate a
.ts module here which mirrors the
targetLocales settings in your config file as exported variables. The generated module will look something like this:
configureLocalization, passing an object with the following properties:
sourceLocale: string: The
sourceLocalevariable exported by your generated
targetLocales: string: The
targetLocalesvariable exported by your generated
loadLocale: (locale: string) => Promise<LocaleModule>: A function that loads a localized template. Returns a promise that resolves to the generated localized template module for the given locale code. See Approaches for loading locale modules for examples of functions you can use here.
configureLocalization returns an object with the following properties:
getLocale: Function that returns the active locale code. If a new locale has started loading,
getLocalewill continue to return the previous locale code until the new one has finished loading.
setLocale: Function that begins switching the active locale to the given code, and returns a promise that resolves when the new locale has loaded. Example usage:
Automatically re-renderPermalink to “Automatically re-render”
To automatically trigger a re-render of your component each time the active locale switches, apply the
updateWhenLocaleChanges function in your
@localized decorator to your class when writing TypeScript.
Status eventPermalink to “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).
Perform other localization related tasks (e.g. setting a locale preference cookie).
Event typesPermalink to “Event types”
detail.status string property tells you what kind of status change has occured, and can be either
A new locale has started to load.
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
loadingevent is dispatched, and no
errorevent will be dispatched for the first request.
loadingstatus can be followed by a
A new locale has successfully loaded and is ready for rendering.
readyLocale: string: Code of the locale that has successfully loaded.
readystatus can be followed only by a
A new locale failed to load.
errorLocale: string: Code of the locale that failed to load.
errorMessage: string: Error message from locale load failure.
errorstatus can be followed only by a
Example of using the status eventPermalink to “Example of using the status event”
Approaches for loading locale modulesPermalink to “Approaches for loading locale modules”
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:
Lazy-loadPermalink to “Lazy-load”
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.
Pre-loadPermalink to “Pre-load”
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.
Static importsPermalink to “Static imports”
Use static imports to pre-load all locales in a way that blocks other script on the page.