privatenumber/webpack-localize-assets-plugin

🌐 Localize your Webpack bundle with multiple locales

webpack-localize-assets-plugin

Localization (i18n) plugin for Webpack. Supports multiple locales.

Used by StackOverflow.com

Features

• Create bundles with localization baked in
• Suports single & multiple locales
• Blazing fast!

How does it compare to i18n-webpack-plugin? Answered in the FAQ.

🚀 Install

npm i -D webpack-localize-assets-plugin

🚦 Quick setup

• Import webpack-localize-assets-plugin.
• Include [locale] in output.filename to indicate where the locale name should go in the output file.
• Register webpack-localize-assets-plugin with locales passed in.

In webpack.config.js:

+ const LocalizeAssetsPlugin = require('webpack-localize-assets-plugin')

  const locales = {
      en: { ... },
      es: { ... },
      ja: { ... },
      ...
  }

  module.exports = {
      ...,

      output: {
+         filename: '[name].[locale].js',
          ...
      },

      plugins: [
          ...,
+         new LocalizeAssetsPlugin({
+             locales
+         })
      ]
  }

⚙️ Options

locales

Required

Type:

type Locales = {
    [locale: string]: string | {
        [stringKey: string]: string
    }
}

An object containing all the localization strings.

The key should be the locale name, and the value can either be the path to the locale JSON file or an object mapping the string key to the localized string.

Using a JSON path has the advantage of automatically detecting changes across compilations, which is useful in development.

Example:

new LocalizeAssetsPlugin({
    locales: {
        en: './locales/en.json',
        es: './locales/es.json'
        // ...
    }
    // ...
})

Or:

new LocalizeAssetsPlugin({
    locales: {
        en: {
            helloWorld: 'Hello World!',
            goodbyeWorld: 'Goodbye World!'
            // ...
        },
        es: {
            helloWorld: '¡Hola Mundo!',
            goodbyeWorld: '¡Adiós Mundo!'
            // ...
        }
        // ...
    }
    // ...
})

functionName

Type: string

Default: __

The function name to use to detect localization string keys.

const message = __('helloWorld') // => 'Hello world!'

throwOnMissing

Type: boolean

Default: false

Throw an error if a string key is not found in a locale object.

sourceMapForLocales

Type: string[]

An array of locales that source-maps should be emitted for. Source-maps are enabled via devtool.

warnOnUnusedString

Type: boolean

Default: false

Enable to see warnings when unused string keys are found.

localizeCompiler

Type:

type LocalizeCompiler = {
    // localizer function name (eg. __)
    [functionName: string]: (
        this: LocalizeCompilerContext,
        localizerArguments: string[],
        localeName: string,
    ) => string
}

Default:

const localizeCompiler = {
    __(localizerArguments) {
        const [key] = localizerArguments
        const keyResolved = this.resolveKey()
        return keyResolved ? JSON.stringify(keyResolved) : key
    }
}

An object of functions to generate a JS string to replace the __() call with. The object key is the localize function name, and its function gets called for each localize function call (eg. __(...)) for each locale. This allows you to have multiple localization functions, with separate compilation logic for each of them.

Note, you cannot use both functionName and localizeCompiler. Simply set the function name as a key in the localizeCompiler object instead.

localizerArguments

An array of strings containing JavaScript expressions. The expressions are stringified arguments of the original call. So localizerArguments[0] will be a JavaScript expression containing the translation key.

localeName

The name of the current locale

this context

Name	Type	Description
resolveKey	(key?: string) => string	A function to get the localized data given a key. Defaults to the key passed in.
emitWarning	(message: string) => void	Call this function to emit a warning into the Webpack build.
emitError	(message: string) => void	Call this function to emit an error into the Webpack build.
callNode	CallExpression	AST node representing the original call to the localization function (eg. __()).

localizeCompiler must return a string containing a JavaScript expression. The expression will be injected into the bundle in the place of the original __() call. The expression should represent the localized string.

You can use localizeCompiler to do inject more localization logic (eg. pluralization).

💁‍♀️ FAQ

How does this work and how is it so fast?

This plugin has two modes: Single-locale and Multi-locale.

In Single-locale mode, it works just like i18n-webpack-plugin. It replaces the localization calls with localized strings during Webpack's module parsing stage. Since there is only one locale, localization only needs to be done once at the earliest possible stage.

In Multi-locale mode, it inserts placeholders instead of the localized strings at the module parsing stage. After minification, all assets are duplicated for each locale and the placeholders are replaced with the localized strings via find-and-replace.

The speed gains come from:

• Applying localization to minified assets. By doing so, we can avoid re-minifying the assets for each locale.
• Using find-and-replace to localize. Find-and-replace is literally just looking for a pattern in a string and replacing it, so there is no AST parsing costs incurred for each locale.

How does this compare to i18n-webpack-plugin?

First of all, thank you to i18n-webpack-plugin for the original idea and implementation and serving the community.

webpack-localize-assets-plugin vs i18n-webpack-plugin:

• Is actively maintained webpack-localize-assets-plugin is actively maintained. i18n-webpack-plugin is no longer developed/maintained and has been archived with no official alternative.
• Has Wepback 5 support webpack-localize-assets-plugin supports Webpack 4 and 5. i18n-webpack-plugin only supports up to Webpack 4
• Is optimized for multiple locales webpack-localize-assets-plugin is designed to support multiple locales efficiently (and it's blazing fast!). i18n-webpack-plugin only supports one locale so building with multiple locales requires complete re-builds for each one.

How does this approach compare to run-time localization?

There are two approaches to localization:

• Build-time localization Happens during building/compiling. Localized strings are baked into the assets basically by find-and-replace. This plugin is an example of build-time localization.
• Run-time localization Happens when the application is running. An asset with localized strings is loaded and strings are referenced by unique key.

Here is a comparison:

	Run-time	Build-time
Output size	Small. Application code is agnostic to locale so it only needs to be produced once. Locale data files are produced for each locale to be loaded by application at run-time.	Large. The entire build is multiplied for every locale. The impact of this multiplication increases with assets that don't require localization (eg. source maps, vendor chunks). Comparing the size of one locale between build-time and run-time, build-time has a slight advantage because there is no "loading overhead" (requesting locale data, long reference keys, etc.). This difference is small but can be negligible after good minification & compression.
Build time	Fast. It's a lot faster because the build only needs to be produced once. Each locale data needs to be produced but there's no processing cost.	Slow. Build speed gets slower with size; so with the build being multiplied for each locale, it's very slow. Although optimizations (like this plugin) can apply localization post-bundling to re-use bundles across multiple locales, it's still a lot slower because large assets take time to localize and write to disk. This gets much slower when enabling things like source maps. To improve speed, you might enable source maps only for the main locale at the cost of debugging experience in other locales.
Loading time	Fast. Although initial page-load might need to request at least two assets instead of one (localization data and application), this can still be very fast with minification & compression. Even faster when using HTTP/2 multiplexing and preloading/async. There's also a notable benefit of fast locale switching. When a user changes their locale, only the new locale asset needs to be loaded because the application code (the larger asset) is already loaded or will have a cache-hit.	Fast. Since localization is baked-in, there is no need to load an additional asset of just locale strings. However, there is a large cost to when users switch locales as the entire app will need to be re-loaded and there will be no cache-hits if it's a new locale.

Sponsors