🔍

i18n-extractor

Extract translation keys and intelligently merge with existing files

Overview

i18n-extractoris a CLI tool that extracts all translation keys wrapped with the t() function from your code, generates per-language JSON files, and intelligently merges them with existing translations.

✓Automatically extract translation keys from code

✓Preserve all existing translations

✓Smart merge that only adds new keys

✓Sort keys alphabetically

✓Detailed stats and reports

Installation

Install globally (recommended):

npm install -g i18nexus-tools

Or run directly with npx:

npx i18n-extractor

Basic Usage

Basic Extraction and Merging

npx i18n-extractor -p "app/**/*.tsx" -d "./locales"

Extracts translation keys from all .tsx files in the 'app' directory and saves them to the 'locales' folder.

Create specific language files

npx i18n-extractor -l "en,ko,ja"

Creates English, Korean, and Japanese translation files.

Preview Mode

npx i18n-extractor --dry-run

Checks extractable keys and stats without modifying files.

How it works

Code Scan

Scans all files matching the specified pattern to find t() function calls.

// Looks for code like this:
t("Welcome")
t("Get Started")
t(\`Hello \${name}\`)

Key Extraction

Extracts the first argument of the t() function as the translation key.

// Extracted keys:
"Welcome"
"Get Started"
"Hello \${name}"

Merge with existing translations

Reads existing translation files, adds only new keys, and preserves all existing translations.

Existing File:

{
  "안녕": "Hello",
  "환영합니다": "Welcome"
}

After Merge:

{
  "안녕": "Hello",
  "시작하기": "시작하기",
  "환영합니다": "Welcome"
}

Save File

Saves JSON files for each language with sorted keys and displays stats.

✓ Extraction complete
  - New keys: 5
  - Existing keys: 120
  - Total keys: 125
  - Files: locales/ko.json, locales/en.json

Command Options

--pattern, -pString

Specifies the glob pattern for files to scan.

--pattern "app/**/*.{ts,tsx}"

--directory, -dString

Specifies the directory path to save translation files.

--directory "./locales"

--languages, -lString

Specifies the language files to create, separated by commas. Default: en,ko

--languages "en,ko,ja,zh"

--dry-runFlags

Displays extracted keys and stats without actually creating files.

--help, -hFlags

Displays the help message.

Example Output

Initial Extraction (New Project)

$ npx i18n-extractor -p "app/**/*.tsx" -d "./locales"

🔍 Scanning files...
   Found 25 files

📝 Extracting translation keys...
   Found 45 unique keys

📁 Creating translation files...
   ✓ locales/ko.json (45 keys)
   ✓ locales/en.json (45 keys)

✅ Extraction complete!
   - New keys: 45
   - Total keys: 45

Incremental Update (Existing Project)

$ npx i18n-extractor -p "app/**/*.tsx" -d "./locales"

🔍 Scanning files...
   Found 30 files

📝 Extracting translation keys...
   Found 52 unique keys

📁 Merging with existing translations...
   Existing keys: 45
   New keys: 7
   
   ✓ locales/ko.json (52 keys, +7 new)
   ✓ locales/en.json (52 keys, +7 new)

✅ Extraction complete!
   - New keys: 7
   - Existing keys: 45
   - Total keys: 52
   
💡 Don't forget to translate the new keys in en.json

Smart merge feature

Guarantees during merge:

✓
100% preservation of existing translations
Never overwrites already translated keys. Manually written translations are kept safe.
✓
Add new keys only
Only new keys added to the code will be added to the translation file.
✓
Alphabetical Sorting
All keys are sorted alphabetically, making them easy to find and keeping git diffs clean.
✓
Independent management per language
Each language file is managed independently; changes in one language do not affect others.

Best Practices

✅Run frequently

Run the extractor whenever you add new features to keep translation files up-to-date.

✅Integrate into CI/CD

Add --dry-run to your build process to check for missing keys.

# package.json
"scripts": {
  "check:i18n": "i18n-extractor --dry-run"
}

✅Version control for translation files

Commit the generated translation files to Git to share with your team.

💡Add English translations

After running the extractor, open en.json and add English translations for the newly added keys.