🌍 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.

$3

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

---

📦 Installation

`bash
npm install -g langcleaner
`

---

🛠 Commands & Usage

$3

Run the entire pipeline in one go:

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

Options:

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

$3

| 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:

`plaintext
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
`

$3

Before dedupe:

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

After dedupe:

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

$3

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.

---