langcleaner 1.0.0

package/README.md

@@ -0,0 +1,153 @@
+# 🌍 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
+
+```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
+
+### ⚡ Full Maintenance (Recommended)
+
+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.
+
+### 🔍 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:
+
+```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
+```
+
+### Example JSON Snippets
+
+**Before `dedupe`:**
+
+```json
+{
+  "save": "Submit",
+  "apply": "Submit",
+  "cancel": "Cancel"
+}
+```
+
+**After `dedupe`:**
+
+```json
+{
+  "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.
+
+---

package/bin/index.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import path from "path";
+import fs from "fs";
+
+// Command Imports
+import dedupe from "../src/commands/dedupe.js";
+import applyCodeUpdates from "../src/commands/applyCodeUpdates.js";
+import findUnusedKeys from "../src/commands/findUnusedKeys.js";
+import findMissingTranslations from "../src/commands/findMissingTranslations.js";
+import syncLang from "../src/commands/syncLang.js";
+import syncAll from "../src/commands/syncAll.js";
+
+program
+  .name("langcleaner")
+  .description("I18n nested JSON cleaner & synchronization CLI tool")
+  .version("1.0.0");
+
+/* --- THE SNOWBALL EFFECT ---
+  Each command follows a prioritized path logic:
+  1. Check for a "previously cleaned" version in ./output/{lang}/cleaned-{file}.json.
+  2. If not found, fallback to the original source path.
+  This allows the maintenance pipeline to build upon the results of previous steps.
+*/
+
+/**
+ * 1. DEDUPE
+ * Merges keys sharing identical values.
+ * Sample: langcleaner dedupe ./locales/en.json --fix --sort
+ */
+program
+  .command("dedupe <masterPath>")
+  .description("Find repetitive values and generate an update-mapping.json")
+  .option("--fix", "Generate a cleaned JSON file in the output folder")
+  .option("--sort", "Sort keys alphabetically in the output file")
+  .action(dedupe);
+
+/**
+ * 2. APPLY CODE UPDATES
+ * Renames keys in source files based on dedupe mapping.
+ * Sample: langcleaner apply-code-updates ./output/en/update-mapping.json ./src
+ */
+program
+  .command("apply-code-updates <mappingPath> <projectDir>")
+  .description("Update source code references based on the dedupe mapping file")
+  .action(applyCodeUpdates);
+
+/**
+ * 3. FIND UNUSED KEYS
+ * Removes keys from JSON that aren't found in the code.
+ * Sample: langcleaner find-unused-keys ./locales/en.json ./src --fix
+ */
+program
+  .command("find-unused-keys <masterPath> <projectDir>")
+  .description("Find and optionally remove i18n keys not referenced in code")
+  .option("--fix", "Generate a cleaned version (removes unused keys)")
+  .action(async (masterPath, projectDir, options) => {
+    await findUnusedKeys(masterPath, projectDir, options.fix);
+  });
+
+/**
+ * 4. FIND MISSING TRANSLATIONS
+ * Detects keys in code missing from JSON.
+ * Sample: langcleaner find-missing-translations ./locales/en.json ./src --fix
+ */
+program
+  .command("find-missing-translations <masterPath> <projectDir>")
+  .description("Find keys present in code but missing from the master JSON file")
+  .option("--fix", "Automatically add missing keys to the cleaned file as stubs")
+  .action(async (masterPath, projectDir, options) => {
+    await findMissingTranslations(masterPath, projectDir, options.fix);
+  });
+
+/**
+ * 5. SYNC SINGLE LANGUAGE
+ * Syncs one specific target to match the master structure.
+ * Sample: langcleaner sync-lang ./locales/en.json ./locales/tr.json
+ */
+program
+  .command("sync-lang <masterPath> <targetPath>")
+  .description("Sync a single target file structure to match the master file")
+  .action(syncLang);
+
+/**
+ * 6. SYNC ALL LANGUAGES
+ * Bulk syncs all files in a folder against the master.
+ * Sample: langcleaner sync-all ./locales/en.json ./locales
+ */
+program
+  .command("sync-all <masterPath> <localesDir>")
+  .description("Sync all JSON files in a directory to match the master structure")
+  .action(syncAll);
+
+/**
+ * 7. FULL MAINTENANCE (THE AUTOMATED PIPELINE)
+ * Runs the full sequence: Dedupe -> Apply -> Unused -> Missing -> Sync.
+ * Sample: langcleaner maintenance ./locales/en.json ./src --fix
+ */
+program
+  .command("maintenance <masterPath> <projectDir>")
+  .description("Run full cycle: Dedupe -> Update Code -> Clean Unused -> Find Missing -> Sync All")
+  .option("--fix", "Automatically apply changes to JSON and source code")
+  .action(async (masterPath, projectDir, options) => {
+    const langName = path.basename(masterPath, ".json");
+    const langFileName = path.basename(masterPath);
+    const outDir = path.join(process.cwd(), "output", langName);
+    const mappingFile = path.join(outDir, "update-mapping.json");
+    const cleanedFile = path.join(outDir, `cleaned-${langFileName}`);
+
+    console.log("\n🚀 Starting Full Project Maintenance...");
+    console.log("──────────────────────────────────────────────────");
+    
+    // Step 1: Dedupe (Initial Clean)
+    console.log("\n[1/5] Deduping values...");
+    await dedupe(masterPath, { fix: options.fix, sort: true });
+
+    // Step 2: Update Code (Requires mapping from Step 1)
+    if (options.fix) {
+      console.log("\n[2/5] Updating source code references...");
+      await applyCodeUpdates(mappingFile, projectDir);
+    }
+
+    // Step 3: Remove Unused (Refines Clean)
+    console.log("\n[3/5] Cleaning unused keys...");
+    await findUnusedKeys(masterPath, projectDir, options.fix);
+
+    // Step 4: Audit/Add Missing (Finalizes Clean)
+    console.log("\n[4/5] Checking and adding missing translations...");
+    await findMissingTranslations(masterPath, projectDir, options.fix);
+
+    // Step 5: Global Synchronization
+    // Priority: Use the fully processed 'cleaned' file if it exists, otherwise use original.
+    const syncSource = (options.fix && fs.existsSync(cleanedFile)) ? cleanedFile : masterPath;
+    
+    console.log(`\n[5/5] Syncing all languages using: ${path.basename(syncSource)}...`);
+    await syncAll(syncSource, path.dirname(masterPath));
+
+    console.log("\n──────────────────────────────────────────────────");
+    console.log("✅ Maintenance completed! Review results in the 'output' folder.");
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "langcleaner",
+  "version": "1.0.0",
+  "description": "Smart i18n maintenance tool: dedupe keys, prune unused translations, and sync nested JSON structures.",
+  "main": "bin/index.js",
+  "type": "module",
+  "bin": {
+    "langcleaner": "./bin/index.js"
+  },
+  "scripts": {
+    "start": "node bin/index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "json-cleaner",
+    "dedupe",
+    "unused-keys",
+    "localization",
+    "translate",
+    "refactor",
+    "cli"
+  ],
+  "author": "Recep Yalcin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/recyalcin/langcleaner.git"
+  },
+  "bugs": {
+    "url": "https://github.com/recyalcin/langcleaner/issues"
+  },
+  "homepage": "https://github.com/recyalcin/langcleaner#readme",
+  "dependencies": {
+    "commander": "^11.1.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/src/commands/applyCodeUpdates.js

@@ -0,0 +1,60 @@
+import fs from "fs";
+import path from "path";
+import { getAllFiles, loadJson } from "../utils/fileUtils.js";
+
+
+export default async function applyCodeUpdates(mappingFile, projectPath) {
+  if (!fs.existsSync(mappingFile)) {
+    console.error(`❌ Error: Mapping file not found at ${mappingFile}`);
+    return;
+  }
+
+  // updateMapping: { "auth.login.old": "auth.login.new" }
+  const { updateMapping } = loadJson(mappingFile);
+  const files = getAllFiles(projectPath, [".js", ".jsx", ".ts", ".tsx", ".vue", ".html", ".svelte"]);
+  
+  console.log(`\n🛠  Updating code references...`);
+  console.log(`──────────────────────────────────────────────────`);
+
+  let fileCount = 0;
+  let replacementCount = 0;
+
+  files.forEach(file => {
+    let content = fs.readFileSync(file, "utf8");
+    let isModified = false;
+
+    for (const [oldKey, newKey] of Object.entries(updateMapping)) {
+      /**
+       * REGEX STRATEGY:
+       * 1. (['"`]) : Opening quote (single, double, or backtick)
+       * 2. ${escapedOldKey} : The exact i18n path to be replaced
+       * 3. (['"`]) : Closing quote
+       * * This structure catches:
+       * - t("auth.button")
+       * - translation['auth.button']
+       * - [ "auth.button" ]
+       * - i18nKey="auth.button"
+       */
+      const escapedOldKey = oldKey.replace(/\./g, "\\.");
+      const regex = new RegExp(`(['"\`])${escapedOldKey}(['"\`])`, "g");
+
+      if (regex.test(content)) {
+        // $1 and $2 put the captured quotes back, replacing only the key inside
+        content = content.replace(regex, `$1${newKey}$2`);
+        isModified = true;
+        replacementCount++;
+      }
+    }
+
+    if (isModified) {
+      fs.writeFileSync(file, content, "utf8");
+      console.log(`  ✔ Updated: ${path.relative(projectPath, file)}`);
+      fileCount++;
+    }
+  });
+
+  console.log(`──────────────────────────────────────────────────`);
+  console.log(`✅ Update Complete!`);
+  console.log(`  • ${replacementCount} key references replaced.`);
+  console.log(`  • ${fileCount} files updated.`);
+}

package/src/commands/dedupe.js

@@ -0,0 +1,85 @@
+import path from "path";
+import { loadJson, writeJson, ensureDir } from "../utils/fileUtils.js";
+import { dedupeValues } from "../utils/dedupeUtils.js";
+import { sortJsonObject } from "../utils/sortUtils.js";
+
+/**
+ * Finds repetitive values in the language file, reports them, and optionally cleans them.
+ * @param {string} file - Path to the language file (e.g., ./locales/en.json)
+ * @param {object} options - CLI options (--fix, --sort)
+ */
+export default async function dedupe(file, options) {
+  if (!file) {
+    console.error("❌ Error: Please provide a valid language file path.");
+    return;
+  }
+
+  // 1. Prepare File and Language Info
+  const json = loadJson(file);
+  const fileName = path.basename(file);
+  const langName = path.basename(file, ".json");
+  const absoluteSourcePath = path.resolve(file); // Get full path for the report
+
+  // 2. Set Output Directory
+  const outDir = path.join(process.cwd(), "output", langName);
+  ensureDir(outDir);
+
+  console.log(`\n🔍 Analyzing [${fileName}]...`);
+
+  // 3. Deduplication Logic
+  const { cleaned, removedValues, updateMapping } = dedupeValues(json);
+  const duplicateCount = Object.keys(removedValues).length;
+
+  // 4. Enhanced Report Data (Matching the format of other commands)
+  const reportPath = path.join(outDir, `repetitive-keys-report.json`);
+  const mappingPath = path.join(outDir, `update-mapping.json`);
+
+  const reportData = {
+    timestamp: new Date().toISOString(),
+    config: {
+      sourceFile: fileName,
+      absoluteSourcePath: absoluteSourcePath,
+      isCleaned: !!options.fix,
+      isSorted: !!options.sort
+    },
+    summary: {
+      totalDuplicatesFound: duplicateCount
+    },
+    details: {
+      duplicates: removedValues,
+      mapping: updateMapping
+    }
+  };
+
+  // Write reports
+  writeJson(reportPath, reportData);
+  
+  if (duplicateCount > 0) {
+    // We save a clean version of the mapping file for the code-updater to read easily
+    writeJson(mappingPath, { updateMapping });
+  }
+
+  // 5. FIX & SORT Operations
+  if (options.fix && duplicateCount > 0) {
+    let finalJson = cleaned;
+
+    if (options.sort) {
+      console.log("  Sorting keys alphabetically (recursive)...");
+      finalJson = sortJsonObject(cleaned);
+    }
+
+    const cleanedFile = path.join(outDir, `cleaned-${fileName}`);
+    writeJson(cleanedFile, finalJson);
+    
+    console.log(`  ✅ Success: Cleaned file created at ${cleanedFile}`);
+  } else if (duplicateCount > 0) {
+    console.log(`  ℹ️  ${duplicateCount} duplicates found. Use --fix to clean them.`);
+  } else {
+    console.log(`  ✅ Great! No repetitive values found.`);
+  }
+
+  console.log(`  📄 Report: ${reportPath}`);
+  if (duplicateCount > 0) {
+    console.log(`  🔗 Mapping: ${mappingPath} (Ready for apply-code-updates)`);
+  }
+}

package/src/commands/findMissingTranslations.js

@@ -0,0 +1,115 @@
+import fs from "fs";
+import path from "path";
+import { getAllFiles, loadJson, writeJson, ensureDir } from "../utils/fileUtils.js";
+
+/* ------------------ HELPERS ------------------ */
+
+function extractKeysFromContent(content) {
+  const keys = new Set();
+  const patterns = [
+    /\b\$?t\s*\(\s*["'`]([^"'`$]+?)["'`]/g,
+    /\b(?:i18n|i18next)\.t\s*\(\s*["'`]([^"'`$]+?)["'`]/g,
+    /(?:id|i18nKey)=["'`]([^"'`]+?)["'`]/g,
+    /\[\s*["'`]([^"'`$]+?)["'`]\s*\]/g
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      if (match[1] && match[1].trim().length > 0) keys.add(match[1]);
+    }
+  }
+  return keys;
+}
+
+function flattenKeys(obj, prefix = "", res = {}) {
+  for (const key in obj) {
+    const value = obj[key];
+    const newKey = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      flattenKeys(value, newKey, res);
+    } else {
+      res[newKey] = value;
+    }
+  }
+  return res;
+}
+
+function setDeep(obj, path, value) {
+  const parts = path.split(".");
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (!current[part] || typeof current[part] !== "object") {
+      current[part] = {};
+    }
+    current = current[part];
+  }
+  const lastPart = parts[parts.length - 1];
+  if (!(lastPart in current)) {
+    current[lastPart] = value;
+  }
+}
+
+/* ------------------ MAIN COMMAND ------------------ */
+
+export default async function findMissingTranslations(masterFile, projectDir, fix = false) {
+  if (!fs.existsSync(masterFile)) {
+    console.error(`❌ Error: Master language file not found at ${masterFile}`);
+    return;
+  }
+
+  const langFileName = path.basename(masterFile);
+  const langName = path.basename(masterFile, ".json");
+  const outDir = path.join(process.cwd(), "output", langName);
+  
+  const previouslyCleaned = path.join(outDir, `cleaned-${langFileName}`);
+  const sourcePath = fs.existsSync(previouslyCleaned) ? previouslyCleaned : masterFile;
+
+  ensureDir(outDir);
+
+  const masterData = loadJson(sourcePath);
+  const masterKeys = new Set(Object.keys(flattenKeys(masterData)));
+  const files = getAllFiles(projectDir, [".js", ".jsx", ".ts", ".tsx", ".vue", ".html", ".svelte"]);
+  const usedInCode = new Set();
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, "utf-8");
+    extractKeysFromContent(content).forEach(k => usedInCode.add(k));
+  }
+
+  const missing = Array.from(usedInCode).filter(key => !masterKeys.has(key));
+
+  if (fix && missing.length > 0) {
+    missing.forEach(key => setDeep(masterData, key, "")); 
+    writeJson(path.join(outDir, `cleaned-${langFileName}`), masterData);
+    console.log(`✨ Success: Added ${missing.length} stub keys to cleaned file.`);
+  }
+
+  // --- UPDATED REPORT STRUCTURE ---
+  const reportPath = path.join(outDir, "missing-keys-report.json");
+  const reportData = {
+    timestamp: new Date().toISOString(),
+    config: {
+      comparedAgainst: sourcePath,
+      projectDirectory: path.resolve(projectDir), // Shows the full absolute path of the scanned code
+      totalFilesScanned: files.length
+    },
+    summary: { 
+      uniqueKeysInCode: usedInCode.size, 
+      missingKeysCount: missing.length 
+    },
+    missingKeys: missing.sort()
+  };
+
+  writeJson(reportPath, reportData);
+
+  console.log(`──────────────────────────────────────────`);
+  if (missing.length === 0) {
+    console.log(`✅ Success: All keys found in code are defined.`);
+  } else {
+    console.log(`❌ Found ${missing.length} keys missing from ${path.basename(sourcePath)}:`);
+    missing.slice(0, 10).forEach(k => console.log(` • ${k}`));
+    if (missing.length > 10) console.log(` • ...and ${missing.length - 10} more.`);
+    console.log(`\n📂 Report saved to: ${reportPath}`);
+  }
+}

package/src/commands/findUnusedKeys.js

@@ -0,0 +1,114 @@
+import fs from "fs";
+import path from "path";
+import { getAllFiles, ensureDir, writeJson, loadJson } from "../utils/fileUtils.js";
+
+/* ------------------ HELPERS ------------------ */
+
+function flattenKeys(obj, prefix = "", res = {}) {
+  for (const key in obj) {
+    const value = obj[key];
+    const newKey = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      flattenKeys(value, newKey, res);
+    } else {
+      res[newKey] = value;
+    }
+  }
+  return res;
+}
+
+function removeEmptyObjects(obj) {
+  for (const key in obj) {
+    if (typeof obj[key] === 'object' && obj[key] !== null && !Array.isArray(obj[key])) {
+      removeEmptyObjects(obj[key]);
+      if (Object.keys(obj[key]).length === 0) {
+        delete obj[key];
+      }
+    }
+  }
+}
+
+function deepDelete(obj, keyPath) {
+  const parts = keyPath.split('.');
+  const last = parts.pop();
+  const target = parts.reduce((acc, part) => acc && acc[part], obj);
+  if (target && typeof target === 'object' && last in target) {
+    delete target[last];
+  }
+}
+
+/* ------------------ MAIN COMMAND ------------------ */
+
+export default async function findUnusedKeys(langFilePath, projectPath, fix = false) {
+  if (!fs.existsSync(langFilePath)) {
+    console.error(`❌ Error: Language file not found at ${langFilePath}`);
+    return;
+  }
+
+  const langFileName = path.basename(langFilePath);
+  const langName = path.basename(langFilePath, ".json");
+  const outDir = path.join(process.cwd(), "output", langName);
+  
+  const previouslyCleaned = path.join(outDir, `cleaned-${langFileName}`);
+  const sourcePath = fs.existsSync(previouslyCleaned) ? previouslyCleaned : langFilePath;
+  
+  if (sourcePath === previouslyCleaned) {
+    console.log(`💡 Note: Using previously cleaned file as source: ${previouslyCleaned}`);
+  }
+
+  ensureDir(outDir);
+  console.log(`\n🔍 Scanning project for unused keys in [${langName}]...`);
+
+  const langData = loadJson(sourcePath);
+  const flatLangKeys = Object.keys(flattenKeys(langData));
+  const projectFiles = getAllFiles(projectPath, [".js", ".jsx", ".ts", ".tsx", ".vue", ".html", ".svelte"]);
+
+  let allProjectContent = "";
+  for (const file of projectFiles) {
+    allProjectContent += fs.readFileSync(file, "utf-8") + "\n";
+  }
+
+  const unused = flatLangKeys.filter(key => {
+    const escapedKey = key.replace(/\./g, "\\.");
+    const regex = new RegExp(`(['"\`])${escapedKey}(['"\`])`, "g");
+    return !regex.test(allProjectContent);
+  });
+
+  const totalKeys = flatLangKeys.length;
+  const unusedCount = unused.length;
+
+  if (fix && unusedCount > 0) {
+    unused.forEach(key => deepDelete(langData, key));
+    removeEmptyObjects(langData); 
+    const cleanFilePath = path.join(outDir, `cleaned-${langFileName}`);
+    writeJson(cleanFilePath, langData);
+    console.log(`✨ Success: Updated cleaned file created at ${cleanFilePath}`);
+  }
+
+  // --- STANDARDIZED REPORT STRUCTURE ---
+  const reportPath = path.join(outDir, "unused-keys-report.json");
+  const reportData = {
+    timestamp: new Date().toISOString(),
+    config: {
+      sourceUsed: path.resolve(sourcePath),
+      projectDirectory: path.resolve(projectPath),
+      totalFilesScanned: projectFiles.length,
+      isCleaned: !!fix
+    },
+    summary: { 
+      totalKeysInJSON: totalKeys, 
+      unusedCount: unusedCount, 
+      usedCount: totalKeys - unusedCount,
+      percentageUnused: totalKeys > 0 ? ((unusedCount / totalKeys) * 100).toFixed(2) + "%" : "0%"
+    },
+    details: {
+      unusedKeys: unused.sort()
+    }
+  };
+
+  writeJson(reportPath, reportData);
+
+  console.log(`──────────────────────────────────────────`);
+  console.log(`✅ Used: ${totalKeys - unusedCount} | ❌ Unused: ${unusedCount}`);
+  console.log(`📂 Report saved to: ${reportPath}`);
+}

package/src/commands/syncAll.js

@@ -0,0 +1,48 @@
+import fs from "fs";
+import path from "path";
+import syncLang from "./syncLang.js";
+
+/**
+ * Syncs all JSON files in a directory with the master language file.
+ * Automatically excludes the master file from being treated as a target.
+ */
+export default async function syncAll(masterFile, dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    console.error(`❌ Error: Locales directory not found at ${dirPath}`);
+    return;
+  }
+
+  const masterAbsPath = path.resolve(masterFile);
+  const masterName = path.basename(masterFile);
+  
+  // Find other .json files in the folder (excluding the master file)
+  const files = fs.readdirSync(dirPath).filter(f => {
+    const fullPath = path.resolve(path.join(dirPath, f));
+    return f.endsWith(".json") && fullPath !== masterAbsPath;
+  });
+
+  console.log(`\n🌍 Bulk Sync Started`);
+  console.log(`──────────────────────────────────`);
+  console.log(`Master Source: ${masterName}`);
+  console.log(`Target Count:  ${files.length} files\n`);
+
+  const results = [];
+
+  for (const file of files) {
+    const fullPath = path.join(dirPath, file);
+    try {
+      await syncLang(masterFile, fullPath);
+      results.push({ lang: file, status: "✔ Success" });
+    } catch (error) {
+      results.push({ lang: file, status: "✖ Failed", error: error.message });
+    }
+  }
+
+  console.log(`──────────────────────────────────`);
+  console.log(`🏁 Sync All Completed!`);
+  results.forEach(res => {
+    const statusMsg = res.status.padEnd(12);
+    const errorDetail = res.error ? `(Error: ${res.error})` : "";
+    console.log(`${statusMsg} ${res.lang} ${errorDetail}`);
+  });
+}

package/src/commands/syncLang.js

@@ -0,0 +1,74 @@
+import path from "path";
+import fs from "fs";
+import { ensureDir, writeJson } from "../utils/fileUtils.js";
+import { syncSingleLang } from "./syncLangCore.js";
+
+/**
+ * Syncs a specific target translation file with the master file.
+ */
+export default async function syncLang(masterFile, targetFile) {
+  if (!fs.existsSync(masterFile) || !fs.existsSync(targetFile)) {
+    console.error(`❌ Error: One or both translation files are missing.`);
+    return;
+  }
+
+  const masterName = path.basename(masterFile);
+  const targetName = path.basename(targetFile);
+  const langCode = path.basename(targetFile, '.json');
+
+  console.log(`🔄 Syncing: ${targetName} ← ${masterName}`);
+
+  // 1. Perform recursive synchronization
+  const { result, missing, extra } = syncSingleLang(masterFile, targetFile);
+
+  // 2. Set output directory (e.g., output/tr for tr.json)
+  const outDir = path.join(process.cwd(), "output", langCode);
+  ensureDir(outDir);
+
+  // 3. Write updated translation file
+  const outFile = path.join(outDir, targetName);
+  writeJson(outFile, result);
+
+  // Helper to count total leaf nodes (actual translation strings)
+  function countKeys(obj) {
+    let count = 0;
+    for (const key in obj) {
+      if (typeof obj[key] === 'object' && obj[key] !== null && !Array.isArray(obj[key])) {
+        count += countKeys(obj[key]);
+      } else {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  // 4. STANDARDIZED REPORT GENERATION
+  const reportData = {
+    timestamp: new Date().toISOString(),
+    config: {
+      masterSource: path.resolve(masterFile),
+      targetSource: path.resolve(targetFile),
+      masterFileName: masterName,
+      targetFileName: targetName
+    },
+    summary: {
+      missingKeysAdded: missing.length,
+      extraKeysRemoved: extra.length,
+      totalKeysInTarget: countKeys(result)
+    },
+    details: {
+      addedKeys: missing.sort(),  // Alphabetical sort for readability
+      removedKeys: extra.sort()   // Alphabetical sort for readability
+    }
+  };
+
+  const reportFile = path.join(outDir, `sync-report.json`);
+  writeJson(reportFile, reportData);
+
+  console.log(`  ✔ File saved: ${outFile}`);
+  console.log(`  ✔ Report: ${reportFile}`);
+  console.log(`  • Added: ${missing.length} missing keys | Removed: ${extra.length} obsolete keys\n`);
+
+  // Return data for syncAll if needed
+  return { success: true, target: targetName, report: reportData };
+}

package/src/commands/syncLangCore.js

@@ -0,0 +1,64 @@
+import { loadJson } from "../utils/fileUtils.js";
+
+/**
+ * Recursive function to synchronize nested objects.
+ * Deeply identifies missing keys and extra keys based on a master object.
+ */
+function recursiveSync(master, target = {}, currentPath = "") {
+  const result = {};
+  const missing = [];
+  const extra = [];
+
+  // 1. Iterate through Master (Build structure and find missing keys)
+  for (const key in master) {
+    const fullPath = currentPath ? `${currentPath}.${key}` : key;
+    const masterValue = master[key];
+    const targetValue = target && typeof target === 'object' ? target[key] : undefined;
+
+    if (typeof masterValue === 'object' && masterValue !== null && !Array.isArray(masterValue)) {
+      // If it's an object, dive deeper
+      const sub = recursiveSync(masterValue, targetValue || {}, fullPath);
+      result[key] = sub.result;
+      missing.push(...sub.missing);
+      extra.push(...sub.extra);
+    } else {
+      // If it's a value: keep target value if it exists, otherwise add empty string
+      if (target && key in target) {
+        result[key] = target[key];
+      } else {
+        result[key] = ""; // New key added as empty
+        missing.push(fullPath);
+      }
+    }
+  }
+
+  // 2. Identify keys in Target that do not exist in Master (Extra/Obsolete keys)
+  if (target && typeof target === 'object') {
+    for (const key in target) {
+      const fullPath = currentPath ? `${currentPath}.${key}` : key;
+      if (!(key in master)) {
+        extra.push(fullPath);
+        // We don't add these to 'result', so they are effectively removed (Cleanup)
+      }
+    }
+  }
+
+  return { result, missing, extra };
+}
+
+/**
+ * Synchronizes a single target language file with the master file.
+ */
+export function syncSingleLang(masterFile, targetFile) {
+  const master = loadJson(masterFile);
+  const target = loadJson(targetFile);
+
+  // Start the recursive synchronization process
+  const { result, missing, extra } = recursiveSync(master, target);
+
+  return { 
+    result, 
+    missing, 
+    extra 
+  };
+}

package/src/utils/dedupeUtils.js

@@ -0,0 +1,103 @@
+/**
+ * 🔵 1. Duplicate KEY temizleme (JSON.parse sonrası)
+ * Not: Standart JSON.parse zaten son anahtarı alır. 
+ * Bu fonksiyon manuel inşa edilen objeler için recursive çalışır.
+ */
+export function dedupeKeys(obj, strategy = "first") {
+  const cleaned = {};
+  const removedKeys = {};
+
+  for (const key in obj) {
+    const value = obj[key];
+    
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      const sub = dedupeKeys(value, strategy);
+      cleaned[key] = sub.cleaned;
+      if (Object.keys(sub.removedKeys).length > 0) {
+        removedKeys[key] = sub.removedKeys;
+      }
+    } else {
+      cleaned[key] = value;
+    }
+  }
+
+  return { cleaned, removedKeys };
+}
+
+/**
+ * 🔵 2. Duplicate VALUE temizleme (JSON Object Mode - Recursive)
+ * Tüm hiyerarşiyi tarar ve aynı değere sahip anahtarları bulur.
+ */
+export function dedupeValues(obj) {
+  const removedValues = {}; 
+  const valueMap = {};      // value -> firstKeyPath
+  const updateMapping = {}; // duplicateKeyPath -> firstKeyPath
+
+  function walk(currentObj, path = "") {
+    const result = {};
+
+    for (const key in currentObj) {
+      const fullPath = path ? `${path}.${key}` : key;
+      const value = currentObj[key];
+
+      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        result[key] = walk(value, fullPath);
+        // Eğer iç obje boş kaldıysa temizle (isteğe bağlı)
+        if (Object.keys(result[key]).length === 0) delete result[key];
+      } else {
+        // Değer kontrolü (Normalizasyon: Boşlukları temizle)
+        const normalized = String(value).trim();
+        
+        if (!Object.prototype.hasOwnProperty.call(valueMap, normalized)) {
+          valueMap[normalized] = fullPath;
+          result[key] = value;
+        } else {
+          removedValues[fullPath] = value;
+          updateMapping[fullPath] = valueMap[normalized];
+          // Duplicate olduğu için result'a eklemiyoruz
+        }
+      }
+    }
+    return result;
+  }
+
+  const cleaned = walk(obj);
+  return { cleaned, removedValues, updateMapping };
+}
+
+/**
+ * 🔵 3. Duplicate VALUE temizleme (RAW MODE)
+ * i18n dosyalarında yorumları korumak kritikse kullanılır.
+ * (Genelde düz yapılar için daha sağlıklıdır)
+ */
+export function dedupeValuesRaw(rawText) {
+  const lines = rawText.split("\n");
+  const valueMap = {}; 
+  const removedValues = {};
+  const updateMapping = {};
+  const outputLines = [];
+
+  const keyValueRegex = /^\s*"([^"]+)"\s*:\s*"([\s\S]*?)"\s*(,)?\s*$/;
+
+  for (const line of lines) {
+    const match = line.match(keyValueRegex);
+    if (!match) {
+      outputLines.push(line);
+      continue;
+    }
+
+    const key = match[1];
+    const value = match[2];
+    const normalized = value.replace(/\s+/g, " ").trim();
+
+    if (!Object.prototype.hasOwnProperty.call(valueMap, normalized)) {
+      valueMap[normalized] = key;
+      outputLines.push(line);
+    } else {
+      removedValues[key] = value;
+      updateMapping[key] = valueMap[normalized];
+    }
+  }
+
+  return { cleanedText: outputLines.join("\n"), removedValues, updateMapping };
+}

package/src/utils/fileUtils.js

@@ -0,0 +1,59 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Loads and parses a JSON file.
+ */
+export function loadJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch (error) {
+    console.error(`❌ Error parsing JSON at ${file}:`, error.message);
+    return {};
+  }
+}
+
+/**
+ * Writes an object to a JSON file with 2-space indentation.
+ */
+export function writeJson(file, data) {
+  fs.writeFileSync(file, JSON.stringify(data, null, 2), "utf-8");
+}
+
+/**
+ * Ensures a directory exists, creating it recursively if needed.
+ */
+export function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Generates a standardized output path: output/[langName]
+ */
+export function getOutputDir(file) {
+  const fileName = path.basename(file, path.extname(file));
+  const outputDir = path.join("output", fileName);
+  ensureDir(outputDir);
+  return outputDir;
+}
+
+/**
+ * Recursively scans a directory for files with specific extensions.
+ * Centralized here to keep commands dry (Don't Repeat Yourself).
+ */
+export function getAllFiles(dir, exts, files = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      // Ignore unnecessary directories to speed up scanning
+      if (!["node_modules", ".git", "dist", "build", ".next", "out"].includes(entry.name)) {
+        getAllFiles(fullPath, exts, files);
+      }
+    } else if (exts.includes(path.extname(entry.name))) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}

package/src/utils/sortUtils.js

@@ -0,0 +1,28 @@
+/**
+ * JSON objesini derinlemesine (recursive) alfabetik olarak sıralar.
+ */
+export function sortJsonObject(obj) {
+  // Eğer gelen veri bir obje değilse veya null ise direkt döndür (recursion sonu)
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+    return obj;
+  }
+
+  // 1. Mevcut objenin anahtarlarını al ve sırala
+  const sortedKeys = Object.keys(obj).sort((a, b) => a.localeCompare(b));
+
+  const result = {};
+
+  // 2. Her bir anahtar için derinleş
+  for (const key of sortedKeys) {
+    const value = obj[key];
+
+    // Eğer değer bir objeyse, onun içine de girip sırala
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      result[key] = sortJsonObject(value); 
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}