i18n-audit-webpack-plugin

Webpack plugin for static i18n locale auditing (useful for monorepos and single apps): detects missing locale files, missing/extra keys, {{…}} placeholder mismatches across languages, plus optional line-based heuristics (JP/style).

If you find this plugin useful, please consider supporting me via GitHub Sponsors, Patreon, KO-FI or PayPal. Thank you!

✨ Features

• ✅ Key parity: compares key trees between corresponding locale files and reports missing / extra keys.
• ✅ {{…}} placeholders: detects placeholder name mismatches for the same key across locales (e.g. {{name}} vs {{fullName}}).
• ✅ Missing locale files: if the base locale file exists but the matching file is missing in another locale.
• ✅ Optional heuristics (Japanese/copy-style focused): line-based rules like long English strings, 。./.。, ASCII . after Japanese, ASCII ? after Japanese, \u00A0, template literals `${…}` inside locale files, etc.
• ✅ Works with Webpack 1 → 5 (peerDependency).

📦 Installation

npm i -D i18n-audit-webpack-plugin

🚀 Usage (Webpack)

CommonJS (webpack.config.js)

const I18nAuditWebpackPlugin = require('i18n-audit-webpack-plugin');

module.exports = {
  plugins: [
    new I18nAuditWebpackPlugin({
      failOnError: true,
      outputFile: 'reports/i18n-audit.txt',
      heuristicLangs: ['ja', 'jp']
    })
  ]
};

ESM (webpack.config.mjs)

import I18nAuditWebpackPlugin from 'i18n-audit-webpack-plugin';

export default {
  plugins: [
    new I18nAuditWebpackPlugin({
      failOnError: true,
      outputFile: 'reports/i18n-audit.txt',
      heuristicLangs: ['ja'],
      useColors: true
    })
  ]
};

📁 Locale folder convention (what the plugin scans)

By default, the plugin scans files matching:

• **/locales/*/**/*.{ts,tsx}

Where locales/<lang>/... is the locale folder code (e.g. en, vi, ja).

Example:

src/locales/en/common.ts
src/locales/vi/common.ts
packages/app/locales/en/errors.ts
packages/app/locales/ja/errors.ts

✅ Supported locale file format

The plugin parses TypeScript AST and prefers:

• export default { ... }
• or export const X = { ... } (an exported object literal)

Example:

export default {
  common: {
    hello: 'Hello {{name}}'
  }
};

📝 What’s in the report?

The report has up to 3 sections (depending on options):

1. Key parity: locale file pairs that have missing/extra keys.
2. Placeholders: keys whose {{…}} placeholders differ between the base locale and another locale.
3. Heuristics: lines “flagged” by the heuristics rules (if enabled).

By default, the report is printed to the console after a Webpack build (hooked at finishModules).

⚙️ Options

Public plugin options:

• failOnError (boolean, default false): pushes an error into the compilation when issues are found (fails build/CI).
• outputFile (string | undefined): when set, writes a plain-text report to a file (path relative to compiler.context (build root) or absolute).
• projectRoot (string | undefined): repo/app root to scan. If not set, the plugin walks up from compiler.context and stops at the first marker found: .git, pnpm-workspace.yaml, lerna.json, rush.json.
• logToConsole (boolean, default true): enable/disable writing the report to stdout.
• useColors (boolean, default: true when stdout is a TTY and NO_COLOR is not set): enable/disable ANSI colors in console output.
• heuristicLangs (string[], default []): locale folder codes to run heuristics on (only runs for languages that exist in the repo; matching is case-insensitive).

📌 Important notes

• The plugin picks a base language automatically: prefers en if present; otherwise uses the first detected language.
• Each “file pair” is matched by the same relative path under locales/<lang>/... (e.g. locales/en/common.ts ↔ locales/vi/common.ts).
• If a locale file uses patterns that are hard to parse (not exporting an object literal), the report will show a parse error and skip deeper comparisons for that pair.
• In watch mode, the audit runs on each build; in non-watch mode, the plugin dedupes runs for the same projectRoot + globs.

📄 License

MIT © 2026 Nguyen Ngoc Long