I18N-tools

Utility for building and compiling I18N bundles.

The project uses tools from FormatJS, if your project uses other tools it may not work for you.

Install globally:npm install @code-obos/i18n-tools -g

Install in project:npm install @code-obos/i18n-tools --save-dev

Breaking Changes (Dependency Modernization)

The latest dependency upgrade introduces breaking changes that must be treated as a major release:

1. The package now runs as ESM ("type": "module").
2. Node.js must be modern enough for the upgraded dependency set (recommended: active LTS).
3. @formatjs/intl peer dependency is upgraded from ^2.8.0 to ^4.1.12.

These changes do not alter the expected CLI output behavior in this repository (verified by tests), but they can affect downstream integrations that depend on CommonJS behavior or older FormatJS versions.

Usage

Usage: i18n-tool [options] [command]
Utility for building and compiling I18N bundles
Options:
-h, --help display helpforcommand
Commands:
build [options] <srcDir><outDir> Bundles files in<srcDir> into i18n files
watch [options] <srcDir><outDir> Starts watching and rebundling files in<srcDir> into i18n files
validate <srcDir> Validate that every locale contains the same set of keys
fix <srcDir> Attempts to fix validation issues by creating missing files
help [command] display helpforcommand

Build/Watch: package and compile intl files

Usage: i18n-tool build [options] <srcDir><outDir>
Bundles files in<srcDir> into i18n files
Arguments:
srcDir source folder of your i18n files
outDir output folder for your i18n bundles
Options:
-f, --format <format> Output format (choices: "script", "json", "jsonlut", "formatjs", default: "formatjs")
--typescript Output script files with typescript (default: false)
--strict Run validation before bundling (default: false)
--ast Compile generated bundles (only availble with formatjs) (default: false)
--lut Generate look-up-table (only availble with formatjs) (default: false)
-t, --timeZone <timezone> Inject timezone into date/time skeletons
-h, --help display helpforcommand
Examples:
- Bundle files into a json file following the formatjs-format
i18n-tool build example/messages example/compiled --ast --lut --typescript

The different formats;

script generates bundle_[locale].js

consttexts={'group-by-page/title': 'The folder structure is preserved in the look-up-table.',};exportdefaulttexts;

Use --typescript to change the file extension

json generates bundle_[locale].json

{
"group-by-page/title": "The folder structure is preserved in the look-up-table."
}

jsonlut generates bundle_[locale].json

{
"group-by-page": {
"title": "The folder structure is preserved in the look-up-table."
}
}

formatjs generates bundle_[locale].json

{
"group-by-page/title": {
"defaultMessage": "The folder structure is preserved in the look-up-table."
}
}

Validate: check if all files are present for all locales

Usage: i18n-tool validate [options] <srcDir>
Validate that every locale contains the same set of keys
Arguments:
srcDir source folder of your i18n files
Options:
-h, --help display helpforcommand

Fix: create missing files

Usage: i18n-tool fix [options] <srcDir>
Attempts to fix validation issues by creating missing files
Arguments:
srcDir source folder of your i18n files
Options:
-h, --help display helpforcommand