Skip to main content

Transform localization mode

In Lit Localize transform mode, a separate folder is generated for each locale. Each folder contains a complete standalone build of your application in that locale, with all runtime @lit/localize code removed:

  • msg calls are replaced with the static localized version of the string or template in each locale.
  • str tags are removed.
  • @lit/localize imports are removed.
  • Templates are optimized to remove unnecessary expressions by folding them into parent templates wherever possible.

For example, given the source:

The following files will be generated:

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

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

  • sourceLocale: string: Required locale code in which source templates in this project are written.

configureTransformLocalization returns an object with the following properties:

The getLocale function returns the active locale code.

In transform mode, the active locale is determined simply by the JavaScript bundle you load. How you determine which bundle to load when your page loads is up to you.

For example, if your application's locale is reflected in the URL path, you can include an inline script in your HTML file that checks the URL and inserts the appropriate <script> tag:

Always validate your locale codes when dynamically choosing a script name. The example below is safe because a script can only be loaded if it matches one of our known locale codes, but if our matching logic was less precise, it could result in bugs or attacks that inject insecure JavaScript.

Implementing logic similar to this on your server so that the appropriate script tag is statically rendered into your HTML file will usually result in the best performance, because the browser will start downloading your script as early as possible.

In transform mode, the setLocale function is not available. Instead, reload the page so that the next load will pick a different locale bundle.

For example, this locale-picker custom element loads a new URL whenever a new locale is selected from a drop-down list:

If you use Rollup, and would prefer an integrated solution instead of running the lit-localize build command separately, import the localeTransformers function from @lit/localize-tools/lib/rollup.js into your Rollup config.

This function generates an array of {locale, transformer} objects, which you can use in conjunction with the transformers option of @rollup/plugin-typescript to generate a separate bundle for each locale.

If you write JavaScript, don't worry about seeing the TypeScript compiler used here. Lit Localize depends on the TypeScript compiler to parse, analyze, and transform your source code — but it handles plain JavaScript files too!

The following rollup.config.mjs generates a minified bundle for each of your locales into ./bundled/<locale>/ directories: