webpack-localize-assets-plugin

1.5.4 verified Sat Apr 25 auth: no javascript

Webpack plugin that localizes bundle output by replacing `__()` calls with locale-specific strings, generating separate files per locale. Current stable version is 1.5.4, released January 2023. Supports Webpack 4 and 5, with TypeScript type definitions included. Key differentiators: supports single and multiple locales, blazing fast, and offers features like source map per locale, warning on unused strings, and a custom localize compiler for advanced replacement logic. Compared to i18n-webpack-plugin, it's more flexible and actively maintained.

Common errors

error TypeError: Cannot destructure property 'locales' of 'undefined' or 'null' ↓

cause Plugin instantiated without options or `locales` option is missing.

fix

Ensure to pass an object with locales property: new LocalizeAssetsPlugin({ locales: {...} })

error Error: Locale 'en' is not found in locale data ↓

cause Locale key in `locales` does not match the key used in the build configuration or a missing locale.

fix

Check that all locale keys in locales match the expected locale names. For single locale mode, ensure the locale key is present in options.

error WARNING: Unused string key 'xyz' found in locale 'en' ↓

cause String key defined in locale but never used via `__()` function.

fix

Either remove the unused key from locale data or use it in code to avoid warning.

error Error: contenthash is not unique across locales ↓

cause Output filename doesn't include `[locale]` or content hash collision.

fix

Add [locale] to output.filename and ensure output.realContentHash is true (Webpack 5).

Warnings

gotcha When using output.filename, you must include `[locale]` placeholder. If omitted, only the last locale will overwrite previous outputs. ↓

fix Use `[locale]` in filename, e.g., `filename: '[name].[locale].js'`.

deprecated In version 1.5.0, using filenames without `[locale]` in single locale mode is allowed, but in multi-locale mode it may cause overwriting. ↓

fix Always include `[locale]` for multi-locale builds.

breaking Webpack 4 compatibility: The plugin uses `Chunk.getModules` which is deprecated in Webpack 5. Fixed in v1.4.2. ↓

fix Upgrade to v1.4.2 or later.

gotcha Content hash (e.g., `[contenthash]`) is not automatically unique across locales. Fixed in v1.3.0 to use `realContentHash`. ↓

fix Upgrade to v1.3.0 or later; ensure `output.hashSalt` is not set.

gotcha If locale values contain double quotes, devtool eval may break. Fixed in v1.5.1 and v1.5.2. ↓

fix Upgrade to v1.5.2 or later.

gotcha Unused locale strings are not automatically minified. Enable `warnOnUnusedString` to detect them. ↓

fix Set `warnOnUnusedString: true` in plugin options.

Install

npm install webpack-localize-assets-plugin

yarn add webpack-localize-assets-plugin

pnpm add webpack-localize-assets-plugin

Imports

LocalizeAssetsPlugin
wrong
```
const { LocalizeAssetsPlugin } = require('webpack-localize-assets-plugin')
```
correct
```
import LocalizeAssetsPlugin from 'webpack-localize-assets-plugin'
```
This is a default export. In CommonJS, use require('webpack-localize-assets-plugin').default or const LocalizeAssetsPlugin = require('webpack-localize-assets-plugin').

Quickstart

Webpack configuration to generate locale-specific bundles using the localize plugin.

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

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[locale].js',
  },
  plugins: [
    new LocalizeAssetsPlugin({
      locales: {
        en: { greeting: 'Hello' },
        es: { greeting: 'Hola' },
      },
      functionName: '__',
    }),
  ],
};