🌍 LangCleaner

The intelligent i18n maintenance toolkit for nested or flat JSON.

LangCleaner is a CLI tool designed to keep your internationalization files clean, synchronized, and perfectly matched to your source code. It doesn't just find problems—it fixes them.

🚀 The Maintenance Pipeline

The most powerful way to use this tool is the maintenance command. It runs a 5-step "Self-Healing" cycle where each step builds upon the last:

1. Dedupe Finds multiple keys with the same translation (e.g., Save and Apply both being "Submit") and merges them.

2. Apply Code Updates Automatically renames those keys in your React/Vue/JS source code to match the new merged keys.

3. Find Unused Keys Scans your code, finds and deletes (if you add --fix) any keys from your JSON that are no longer used.

4. Find Missing Translations Finds keys you wrote in your code (like t("nav.home")) that don't exist in your JSON yet and adds (if you add --fix) them as empty stubs.

5. Sync Lang / Sync All Takes your now-perfect English (or other master) file and forces all other languages (tr.json, de.json, etc.) to match its structure perfectly.

Maintenance Pipeline Diagram

         +---------+
         |  Start  |
         +----+----+
              |
              v
        +-----+-----+
        |   Dedupe  |
        +-----+-----+
              |
              v
   +----------+-----------+
   |   Apply Updates       |
   +----------+-----------+
              |
              v
      +-------+-------+
      |   Clean Unused |
      +-------+-------+
              |
              v
      +-------+-------+
      |  Add Missing   |
      +-------+-------+
              |
              v
        +-----+-----+
        |  Sync All  |
        +-----+-----+
              |
              v
         +----+----+
         |  Finish  |
         +---------+

📦 Installation

npm install -g langcleaner

🛠 Commands & Usage

⚡ Full Maintenance (Recommended)

Run the entire pipeline in one go:

langcleaner maintenance ./locales/en.json ./src --fix

Options:

• --fix: Required to actually update your files. Without it, the tool only generates reports.

🔍 Individual Commands

| Command | Purpose | Sample Usage | | --------------------------- | ------------------------------------ | ------------------------------------------------------------- | | dedupe | Merges duplicate values in JSON | langcleaner dedupe ./locales/en.json --fix | | apply-code-updates | Updates code based on dedupe mapping | langcleaner apply-code-updates ./output/update-mapping.json ./src | | find-unused-keys | Removes dead keys from JSON | langcleaner find-unused-keys ./locales/en.json ./src --fix | | find-missing-translations | Stubs out missing keys in JSON | langcleaner find-missing-translations ./locales/en.json ./src --fix | | sync-lang | Syncs a language to match master | langcleaner sync-lang ./locales/en.json ./locales/de.json | | sync-all | Syncs all languages to match master | langcleaner sync-all ./locales/en.json ./locales |

📂 Understanding the output/ folder

LangCleaner follows a Safety-First approach. It never overwrites your primary master file. Instead, it creates an output/ directory:

output/
└── en/
    ├── cleaned-en.json          <-- Your "Gold Standard" file
    ├── update-mapping.json      <-- Logic used to update code
    ├── unused-keys-report.json  <-- Audit of what was deleted
    └── missing-keys-report.json <-- Audit of what needs translation

Example JSON Snippets

Before dedupe:

{
  "save": "Submit",
  "apply": "Submit",
  "cancel": "Cancel"
}

After dedupe:

{
  "save": "Submit",
  "cancel": "Cancel"
}

Professional Audit Reports

Every report is standardized for your team's review:

• Config: Shows absolute paths and files scanned.
• Summary: High-level stats (e.g., "37% of keys were unused").
• Details: Alphabetical lists of exactly which keys were changed.

💡 Pro-Tips

• Always use a Master: Choose one language (usually English) as your master path.
• Dry Run: Run commands without --fix first to see the JSON reports and verify changes.
• Commit First: Always commit your code to Git before running with --fix so you can easily revert if needed.