poly-lexis 0.9.3 → 0.11.0

package/dist/cli/translations.js

@@ -529,9 +529,100 @@ var init_language_fallback = __esm({
   }
 });
 
-// src/translations/utils/utils.ts
+// src/translations/utils/metadata.ts
+import { createHash } from "crypto";
 import * as fs from "fs";
 import * as path2 from "path";
+function emptyMetadata() {
+  return { version: CURRENT_VERSION, languages: {} };
+}
+function hashSourceValue(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function getMetadataPath(translationsPath) {
+  return path2.join(translationsPath, METADATA_FILE_NAME);
+}
+function metadataExists(translationsPath) {
+  return fs.existsSync(getMetadataPath(translationsPath));
+}
+function readMetadata(translationsPath) {
+  const metadataPath = getMetadataPath(translationsPath);
+  if (!fs.existsSync(metadataPath)) {
+    return emptyMetadata();
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(metadataPath, "utf-8"));
+    return {
+      version: parsed.version ?? CURRENT_VERSION,
+      languages: parsed.languages ?? {}
+    };
+  } catch {
+    return emptyMetadata();
+  }
+}
+function writeMetadata(translationsPath, metadata) {
+  if (!fs.existsSync(translationsPath)) {
+    fs.mkdirSync(translationsPath, { recursive: true });
+  }
+  const metadataPath = getMetadataPath(translationsPath);
+  fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}
+`, "utf-8");
+}
+function setSourceHash(metadata, language, namespace, key, sourceValue) {
+  if (!metadata.languages[language]) {
+    metadata.languages[language] = {};
+  }
+  if (!metadata.languages[language][namespace]) {
+    metadata.languages[language][namespace] = {};
+  }
+  metadata.languages[language][namespace][key] = hashSourceValue(sourceValue);
+  return metadata;
+}
+function getSourceHash(metadata, language, namespace, key) {
+  return metadata.languages[language]?.[namespace]?.[key];
+}
+function pruneMetadata(metadata, sourceKeysByNamespace) {
+  let changed = false;
+  for (const language of Object.keys(metadata.languages)) {
+    const namespaces = metadata.languages[language];
+    for (const namespace of Object.keys(namespaces)) {
+      const sourceKeys = sourceKeysByNamespace[namespace];
+      if (!sourceKeys) {
+        delete namespaces[namespace];
+        changed = true;
+        continue;
+      }
+      for (const key of Object.keys(namespaces[namespace])) {
+        if (!sourceKeys.has(key)) {
+          delete namespaces[namespace][key];
+          changed = true;
+        }
+      }
+      if (Object.keys(namespaces[namespace]).length === 0) {
+        delete namespaces[namespace];
+        changed = true;
+      }
+    }
+    if (Object.keys(namespaces).length === 0) {
+      delete metadata.languages[language];
+      changed = true;
+    }
+  }
+  return changed;
+}
+var METADATA_FILE_NAME, CURRENT_VERSION;
+var init_metadata = __esm({
+  "src/translations/utils/metadata.ts"() {
+    "use strict";
+    init_esm_shims();
+    METADATA_FILE_NAME = ".translations-meta.json";
+    CURRENT_VERSION = 1;
+  }
+});
+
+// src/translations/utils/utils.ts
+import * as fs2 from "fs";
+import * as path3 from "path";
 function flattenObject(obj, prefix = "") {
   const result = {};
   for (const [key, value] of Object.entries(obj)) {
@@ -548,16 +639,16 @@ function isNestedObject(obj) {
   return Object.values(obj).some((value) => typeof value === "object" && value !== null);
 }
 function readTranslations(translationsPath, language) {
-  const langPath = path2.join(translationsPath, language);
-  if (!fs.existsSync(langPath)) {
+  const langPath = path3.join(translationsPath, language);
+  if (!fs2.existsSync(langPath)) {
     return {};
   }
-  const files = fs.readdirSync(langPath).filter((f) => f.endsWith(".json"));
+  const files = fs2.readdirSync(langPath).filter((f) => f.endsWith(".json"));
   const translations = {};
   for (const file of files) {
-    const namespace = path2.basename(file, ".json");
-    const filePath = path2.join(langPath, file);
-    const content = fs.readFileSync(filePath, "utf-8");
+    const namespace = path3.basename(file, ".json");
+    const filePath = path3.join(langPath, file);
+    const content = fs2.readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(content);
     if (isNestedObject(parsed)) {
       translations[namespace] = flattenObject(parsed);
@@ -568,26 +659,26 @@ function readTranslations(translationsPath, language) {
   return translations;
 }
 function writeTranslation(translationsPath, language, namespace, translations) {
-  const langPath = path2.join(translationsPath, language);
-  if (!fs.existsSync(langPath)) {
-    fs.mkdirSync(langPath, { recursive: true });
+  const langPath = path3.join(translationsPath, language);
+  if (!fs2.existsSync(langPath)) {
+    fs2.mkdirSync(langPath, { recursive: true });
   }
-  const filePath = path2.join(langPath, `${namespace}.json`);
-  fs.writeFileSync(filePath, `${JSON.stringify(translations, null, 2)}
+  const filePath = path3.join(langPath, `${namespace}.json`);
+  fs2.writeFileSync(filePath, `${JSON.stringify(translations, null, 2)}
 `, "utf-8");
 }
 function getAvailableLanguages(translationsPath) {
-  if (!fs.existsSync(translationsPath)) {
+  if (!fs2.existsSync(translationsPath)) {
     return [];
   }
-  return fs.readdirSync(translationsPath, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
+  return fs2.readdirSync(translationsPath, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
 }
 function getNamespaces(translationsPath, language) {
-  const langPath = path2.join(translationsPath, language);
-  if (!fs.existsSync(langPath)) {
+  const langPath = path3.join(translationsPath, language);
+  if (!fs2.existsSync(langPath)) {
     return [];
   }
-  return fs.readdirSync(langPath).filter((f) => f.endsWith(".json")).map((f) => path2.basename(f, ".json"));
+  return fs2.readdirSync(langPath).filter((f) => f.endsWith(".json")).map((f) => path3.basename(f, ".json"));
 }
 function sortKeys(obj) {
   const sorted = {};
@@ -598,13 +689,13 @@ function sortKeys(obj) {
   return sorted;
 }
 function ensureTranslationsStructure(translationsPath, languages) {
-  if (!fs.existsSync(translationsPath)) {
-    fs.mkdirSync(translationsPath, { recursive: true });
+  if (!fs2.existsSync(translationsPath)) {
+    fs2.mkdirSync(translationsPath, { recursive: true });
   }
   for (const lang of languages) {
-    const langPath = path2.join(translationsPath, lang);
-    if (!fs.existsSync(langPath)) {
-      fs.mkdirSync(langPath, { recursive: true });
+    const langPath = path3.join(translationsPath, lang);
+    if (!fs2.existsSync(langPath)) {
+      fs2.mkdirSync(langPath, { recursive: true });
     }
   }
 }
@@ -635,8 +726,8 @@ function syncTranslationStructure(translationsPath, languages, sourceLanguage) {
     const targetNamespaces = getNamespaces(translationsPath, language);
     for (const namespace of targetNamespaces) {
       if (!sourceNamespaces.includes(namespace)) {
-        const filePath = path2.join(translationsPath, language, `${namespace}.json`);
-        fs.unlinkSync(filePath);
+        const filePath = path3.join(translationsPath, language, `${namespace}.json`);
+        fs2.unlinkSync(filePath);
         result.removedNamespaces.push({
           language,
           namespace,
@@ -645,9 +736,9 @@ function syncTranslationStructure(translationsPath, languages, sourceLanguage) {
       }
     }
     for (const namespace of sourceNamespaces) {
-      const filePath = path2.join(translationsPath, language, `${namespace}.json`);
+      const filePath = path3.join(translationsPath, language, `${namespace}.json`);
       const sourceFile = sourceTranslations[namespace] || {};
-      if (fs.existsSync(filePath)) {
+      if (fs2.existsSync(filePath)) {
         const targetFile = targetTranslations[namespace] || {};
         let hasOrphanedKeys = false;
         const cleanedFile = {};
@@ -687,12 +778,23 @@ function syncTranslationStructure(translationsPath, languages, sourceLanguage) {
       });
     }
   }
+  if (metadataExists(translationsPath)) {
+    const sourceKeysByNamespace = {};
+    for (const namespace of sourceNamespaces) {
+      sourceKeysByNamespace[namespace] = new Set(Object.keys(sourceTranslations[namespace] || {}));
+    }
+    const metadata = readMetadata(translationsPath);
+    if (pruneMetadata(metadata, sourceKeysByNamespace)) {
+      writeMetadata(translationsPath, metadata);
+    }
+  }
   return result;
 }
 var init_utils = __esm({
   "src/translations/utils/utils.ts"() {
     "use strict";
     init_esm_shims();
+    init_metadata();
   }
 });
 
@@ -724,13 +826,13 @@ __export(init_exports, {
   initTranslations: () => initTranslations,
   loadConfig: () => loadConfig
 });
-import * as fs2 from "fs";
-import * as path3 from "path";
+import * as fs3 from "fs";
+import * as path4 from "path";
 function detectExistingTranslations(projectRoot) {
   const possiblePaths = ["public/static/locales", "public/locales", "src/locales", "locales", "i18n", "translations"];
   for (const possiblePath of possiblePaths) {
-    const fullPath = path3.join(projectRoot, possiblePath);
-    if (fs2.existsSync(fullPath)) {
+    const fullPath = path4.join(projectRoot, possiblePath);
+    if (fs3.existsSync(fullPath)) {
       const languages = getAvailableLanguages(fullPath);
       if (languages.length > 0) {
         return { path: possiblePath, languages };
@@ -760,7 +862,7 @@ function initTranslations(projectRoot, config = {}) {
       languages: validLanguages.length > 0 ? validLanguages : finalConfig.languages
     };
   }
-  const translationsPath = path3.join(projectRoot, finalConfig.translationsPath);
+  const translationsPath = path4.join(projectRoot, finalConfig.translationsPath);
   const languages = finalConfig.languages.length > 0 ? finalConfig.languages : [...DEFAULT_LANGUAGES];
   console.log(`Project root: ${projectRoot}`);
   console.log(`Translations path: ${translationsPath}`);
@@ -772,9 +874,9 @@ function initTranslations(projectRoot, config = {}) {
   }
   ensureTranslationsStructure(translationsPath, languages);
   const sourceLanguage = finalConfig.sourceLanguage;
-  const sourcePath = path3.join(translationsPath, sourceLanguage);
-  const commonPath = path3.join(sourcePath, "common.json");
-  if (!fs2.existsSync(commonPath)) {
+  const sourcePath = path4.join(translationsPath, sourceLanguage);
+  const commonPath = path4.join(sourcePath, "common.json");
+  if (!fs3.existsSync(commonPath)) {
     const sampleTranslations = {
       LOADING: "Loading",
       SAVE: "Save",
@@ -783,7 +885,7 @@ function initTranslations(projectRoot, config = {}) {
       ERROR: "Error",
       SUCCESS: "Success"
     };
-    fs2.writeFileSync(commonPath, `${JSON.stringify(sampleTranslations, null, 2)}
+    fs3.writeFileSync(commonPath, `${JSON.stringify(sampleTranslations, null, 2)}
 `, "utf-8");
     console.log(`Created sample file: ${commonPath}`);
   }
@@ -797,8 +899,8 @@ function initTranslations(projectRoot, config = {}) {
       console.log(`  ${lang}: ${langFiles.map((f) => f.namespace).join(", ")}`);
     }
   }
-  const configPath = path3.join(projectRoot, ".translationsrc.json");
-  if (!fs2.existsSync(configPath)) {
+  const configPath = path4.join(projectRoot, ".translationsrc.json");
+  if (!fs3.existsSync(configPath)) {
     const configContent = {
       $schema: "./node_modules/poly-lexis/dist/translations/core/translations-config.schema.json",
       translationsPath: finalConfig.translationsPath,
@@ -807,7 +909,7 @@ function initTranslations(projectRoot, config = {}) {
       typesOutputPath: finalConfig.typesOutputPath,
       provider: finalConfig.provider
     };
-    fs2.writeFileSync(configPath, `${JSON.stringify(configContent, null, 2)}
+    fs3.writeFileSync(configPath, `${JSON.stringify(configContent, null, 2)}
 `, "utf-8");
     console.log(`Created config file: ${configPath}`);
   }
@@ -816,8 +918,8 @@ function initTranslations(projectRoot, config = {}) {
   console.log("=====");
 }
 function loadConfig(projectRoot) {
-  const configPath = path3.join(projectRoot, ".translationsrc.json");
-  if (!fs2.existsSync(configPath)) {
+  const configPath = path4.join(projectRoot, ".translationsrc.json");
+  if (!fs3.existsSync(configPath)) {
     const existing = detectExistingTranslations(projectRoot);
     if (existing.path && existing.languages.length > 0) {
       console.log(`\u2139\uFE0F  No config found, but detected translations at ${existing.path}`);
@@ -829,7 +931,7 @@ function loadConfig(projectRoot) {
     }
     return DEFAULT_CONFIG;
   }
-  const configContent = fs2.readFileSync(configPath, "utf-8");
+  const configContent = fs3.readFileSync(configPath, "utf-8");
   const config = JSON.parse(configContent);
   if (config.languages) {
     const validation = validateLanguages(config.languages);
@@ -857,8 +959,8 @@ __export(generate_types_exports, {
   generateTranslationTypes: () => generateTranslationTypes
 });
 import { execSync } from "child_process";
-import * as fs3 from "fs";
-import * as path4 from "path";
+import * as fs4 from "fs";
+import * as path5 from "path";
 function extractPluralBaseKeys(keys) {
   const keySet = new Set(keys);
   const baseKeys = /* @__PURE__ */ new Set();
@@ -881,11 +983,11 @@ function generateTranslationTypes(projectRoot = process.cwd()) {
   console.log("Generating i18n types");
   console.log("=====");
   const config = loadConfig(projectRoot);
-  const translationsPath = path4.join(projectRoot, config.translationsPath);
+  const translationsPath = path5.join(projectRoot, config.translationsPath);
   const sourceLanguage = config.sourceLanguage;
-  const outputFilePath = path4.join(projectRoot, config.typesOutputPath);
-  const dirPath = path4.join(translationsPath, sourceLanguage);
-  if (!fs3.existsSync(dirPath)) {
+  const outputFilePath = path5.join(projectRoot, config.typesOutputPath);
+  const dirPath = path5.join(translationsPath, sourceLanguage);
+  if (!fs4.existsSync(dirPath)) {
     throw new Error(`Source language directory not found: ${dirPath}`);
   }
   const namespaces = getNamespaces(translationsPath, sourceLanguage);
@@ -900,12 +1002,12 @@ function generateTranslationTypes(projectRoot = process.cwd()) {
   }
   const pluralBaseKeys = extractPluralBaseKeys(allKeys);
   allKeys = allKeys.concat(pluralBaseKeys);
-  const outputDir = path4.dirname(outputFilePath);
-  if (!fs3.existsSync(outputDir)) {
-    fs3.mkdirSync(outputDir, { recursive: true });
+  const outputDir = path5.dirname(outputFilePath);
+  if (!fs4.existsSync(outputDir)) {
+    fs4.mkdirSync(outputDir, { recursive: true });
   }
   const typeString = typeTemplate(allKeys, namespaces, config.languages);
-  fs3.writeFileSync(outputFilePath, typeString, "utf8");
+  fs4.writeFileSync(outputFilePath, typeString, "utf8");
   console.log(`Generated types with ${allKeys.length} keys and ${namespaces.length} namespaces`);
   console.log(`Output: ${outputFilePath}`);
   try {
@@ -946,8 +1048,8 @@ __export(find_unused_exports, {
   printUnusedKeysResult: () => printUnusedKeysResult
 });
 import { execSync as execSync2, spawnSync } from "child_process";
-import * as fs6 from "fs";
-import * as path10 from "path";
+import * as fs7 from "fs";
+import * as path11 from "path";
 function isRipgrepAvailable() {
   try {
     execSync2("rg --version", { stdio: "ignore" });
@@ -1008,15 +1110,15 @@ function findFiles(rootDir, searchPaths, extensions) {
   ]);
   function scanDirectory(dir) {
     try {
-      const entries = fs6.readdirSync(dir, { withFileTypes: true });
+      const entries = fs7.readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
-        const fullPath = path10.join(dir, entry.name);
+        const fullPath = path11.join(dir, entry.name);
         if (entry.isDirectory()) {
           if (!excludeDirs.has(entry.name)) {
             scanDirectory(fullPath);
           }
         } else if (entry.isFile()) {
-          const ext = path10.extname(entry.name);
+          const ext = path11.extname(entry.name);
           if (extensionSet.has(ext)) {
             files.push(fullPath);
           }
@@ -1026,8 +1128,8 @@ function findFiles(rootDir, searchPaths, extensions) {
     }
   }
   for (const searchPath of searchPaths) {
-    const fullSearchPath = path10.join(rootDir, searchPath);
-    if (fs6.existsSync(fullSearchPath)) {
+    const fullSearchPath = path11.join(rootDir, searchPath);
+    if (fs7.existsSync(fullSearchPath)) {
       scanDirectory(fullSearchPath);
     }
   }
@@ -1035,7 +1137,7 @@ function findFiles(rootDir, searchPaths, extensions) {
 }
 function checkKeyInFile(key, filePath) {
   try {
-    const content = fs6.readFileSync(filePath, "utf-8");
+    const content = fs7.readFileSync(filePath, "utf-8");
     const exactPatterns = [new RegExp(`['"\`]${key}['"\`]`, "g"), new RegExp(`\\b${key}\\b`, "g")];
     for (const pattern of exactPatterns) {
       if (pattern.test(content)) {
@@ -1058,7 +1160,7 @@ function checkPartialMatches(key, files) {
   const foundParts = /* @__PURE__ */ new Set();
   for (const file of filesToCheck) {
     try {
-      const content = fs6.readFileSync(file, "utf-8");
+      const content = fs7.readFileSync(file, "utf-8");
       for (const part of significantParts) {
         if (foundParts.has(part)) continue;
         const partPattern = new RegExp(`\\b${part}\\b`, "gi");
@@ -1078,7 +1180,7 @@ function checkPartialMatches(key, files) {
 }
 function findUnusedKeys(projectRoot = process.cwd()) {
   const config = loadConfig(projectRoot);
-  const translationsPath = path10.join(projectRoot, config.translationsPath);
+  const translationsPath = path11.join(projectRoot, config.translationsPath);
   const sourceLanguage = config.sourceLanguage;
   const searchPaths = config.searchPaths || ["src", "app", "pages", "components"];
   const searchExtensions = config.searchExtensions || [".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte"];
@@ -1227,10 +1329,10 @@ __export(find_duplicates_exports, {
   findDuplicates: () => findDuplicates,
   printDuplicateKeysResult: () => printDuplicateKeysResult
 });
-import * as path11 from "path";
+import * as path12 from "path";
 function findDuplicates(projectRoot = process.cwd()) {
   const config = loadConfig(projectRoot);
-  const translationsPath = path11.join(projectRoot, config.translationsPath);
+  const translationsPath = path12.join(projectRoot, config.translationsPath);
   const sourceLanguage = config.sourceLanguage;
   const namespaces = getNamespaces(translationsPath, sourceLanguage);
   const sourceTranslations = readTranslations(translationsPath, sourceLanguage);
@@ -1310,14 +1412,14 @@ var init_find_duplicates = __esm({
 // src/cli/translations.ts
 init_esm_shims();
 import "dotenv/config";
-import * as fs7 from "fs";
-import * as path12 from "path";
+import * as fs8 from "fs";
+import * as path13 from "path";
 import { parseArgs } from "util";
 import { confirm as confirm2, input as input2, select as select2 } from "@inquirer/prompts";
 
 // src/translations/cli/add-key.ts
 init_esm_shims();
-import * as path5 from "path";
+import * as path6 from "path";
 
 // src/translations/utils/deepl-translate-provider.ts
 init_esm_shims();
@@ -1525,6 +1627,9 @@ var GoogleTranslateProvider = class {
   }
 };
 
+// src/translations/cli/add-key.ts
+init_metadata();
+
 // src/translations/utils/translator.ts
 init_esm_shims();
 var defaultProvider = new GoogleTranslateProvider();
@@ -1553,7 +1658,7 @@ init_generate_types();
 init_init();
 async function addTranslationKey(projectRoot, options) {
   const config = loadConfig(projectRoot);
-  const translationsPath = path5.join(projectRoot, config.translationsPath);
+  const translationsPath = path6.join(projectRoot, config.translationsPath);
   const { namespace, key, value, autoTranslate = false, apiKey } = options;
   const currentProvider = getTranslationProvider();
   const isDefaultGoogleProvider = currentProvider.constructor.name === "GoogleTranslateProvider";
@@ -1587,6 +1692,7 @@ async function addTranslationKey(projectRoot, options) {
   const otherLanguages = config.languages.filter((lang) => lang !== sourceLang);
   if (autoTranslate && apiKey) {
     console.log("\nAuto-translating to other languages...");
+    const metadata = readMetadata(translationsPath);
     for (const lang of otherLanguages) {
       try {
         const targetTranslations = readTranslations(translationsPath, lang);
@@ -1605,6 +1711,7 @@ async function addTranslationKey(projectRoot, options) {
           targetTranslations[namespace][key] = translated;
           const sorted = sortKeys(targetTranslations[namespace]);
           writeTranslation(translationsPath, lang, namespace, sorted);
+          setSourceHash(metadata, lang, namespace, key, value);
           console.log(`  \u2713 ${lang}: "${translated}"`);
           await new Promise((resolve) => setTimeout(resolve, 100));
         } else {
@@ -1614,6 +1721,7 @@ async function addTranslationKey(projectRoot, options) {
         console.error(`  \u2717 ${lang}: Translation failed - ${error instanceof Error ? error.message : "Unknown error"}`);
       }
     }
+    writeMetadata(translationsPath, metadata);
   } else {
     console.log("\nAdding empty values to other languages...");
     for (const lang of otherLanguages) {
@@ -1653,13 +1761,13 @@ init_esm_shims();
 init_schema();
 init_types();
 init_init();
-import * as fs4 from "fs";
-import * as path6 from "path";
+import * as fs5 from "fs";
+import * as path7 from "path";
 import { checkbox, confirm, input, select } from "@inquirer/prompts";
 async function initTranslationsInteractive(projectRoot = process.cwd()) {
   console.log("\n\u{1F30D} Translation System Setup\n");
-  const configPath = path6.join(projectRoot, ".translationsrc.json");
-  const alreadyExists = fs4.existsSync(configPath);
+  const configPath = path7.join(projectRoot, ".translationsrc.json");
+  const alreadyExists = fs5.existsSync(configPath);
   if (alreadyExists) {
     console.log("\u26A0\uFE0F  Configuration file already exists at .translationsrc.json\n");
     const shouldOverwrite = await confirm({
@@ -1828,29 +1936,33 @@ function getLanguageName(code) {
 // src/translations/cli/manage.ts
 init_esm_shims();
 init_utils();
-import * as fs5 from "fs";
-import * as path9 from "path";
+import * as fs6 from "fs";
+import * as path10 from "path";
 
 // src/translations/cli/auto-fill.ts
 init_esm_shims();
-import * as path8 from "path";
+import * as path9 from "path";
+init_metadata();
 init_utils();
 init_init();
 
 // src/translations/cli/validate.ts
 init_esm_shims();
+init_metadata();
 init_utils();
 init_init();
-import * as path7 from "path";
+import * as path8 from "path";
 function validateTranslations(projectRoot = process.cwd()) {
   const config = loadConfig(projectRoot);
-  const translationsPath = path7.join(projectRoot, config.translationsPath);
+  const translationsPath = path8.join(projectRoot, config.translationsPath);
   const sourceLanguage = config.sourceLanguage;
   const missing = [];
   const empty = [];
   const orphaned = [];
+  const stale = [];
   const sourceTranslations = readTranslations(translationsPath, sourceLanguage);
   const sourceNamespaces = getNamespaces(translationsPath, sourceLanguage);
+  const metadata = readMetadata(translationsPath);
   const languages = config.languages.filter((lang) => lang !== sourceLanguage);
   const syncResult = syncTranslationStructure(translationsPath, config.languages, sourceLanguage);
   if (syncResult.createdFiles.length > 0) {
@@ -1887,6 +1999,17 @@ function validateTranslations(projectRoot = process.cwd()) {
             language,
             sourceValue
           });
+        } else if (typeof targetValue === "string") {
+          const recordedHash = getSourceHash(metadata, language, namespace, key);
+          if (recordedHash !== void 0 && recordedHash !== hashSourceValue(sourceValue)) {
+            stale.push({
+              namespace,
+              key,
+              language,
+              sourceValue,
+              currentValue: targetValue
+            });
+          }
         }
       }
       for (const [key, targetValue] of Object.entries(targetKeys)) {
@@ -1902,7 +2025,7 @@ function validateTranslations(projectRoot = process.cwd()) {
     }
   }
   const valid = !missing.length && !empty.length && !orphaned.length;
-  if (valid) {
+  if (valid && !stale.length) {
     console.log("\u2713 All translations are valid!");
   } else {
     if (missing.length > 0) {
@@ -1935,18 +2058,73 @@ function validateTranslations(projectRoot = process.cwd()) {
         console.log(`  ... and ${orphaned.length - 10} more`);
       }
     }
+    if (stale.length > 0) {
+      console.log(
+        `
+\u26A0 Found ${stale.length} potentially outdated translations (source value changed since translation):`
+      );
+      for (const item of stale.slice(0, 10)) {
+        console.log(`  ${item.language}/${item.namespace}.json -> ${item.key}`);
+      }
+      if (stale.length > 10) {
+        console.log(`  ... and ${stale.length - 10} more`);
+      }
+      console.log("  Run auto-fill with --retranslate-changed to update them.");
+    }
   }
   console.log("=====");
-  return { valid, missing, empty, orphaned };
+  return { valid, missing, empty, orphaned, stale };
 }
-function getMissingForLanguage(projectRoot, language) {
+function getMissingForLanguage(projectRoot, language, options = {}) {
   const result = validateTranslations(projectRoot);
   const items = [
     ...result.missing.filter((m) => m.language === language).map((m) => ({ ...m, type: "missing" })),
     ...result.empty.filter((e) => e.language === language).map((e) => ({ ...e, type: "empty" }))
   ];
+  if (options.includeStale) {
+    items.push(
+      ...result.stale.filter((s) => s.language === language).map((s) => ({
+        namespace: s.namespace,
+        key: s.key,
+        language: s.language,
+        sourceValue: s.sourceValue,
+        type: "stale"
+      }))
+    );
+  }
   return items;
 }
+function ensureBaselineMetadata(projectRoot = process.cwd()) {
+  const config = loadConfig(projectRoot);
+  const translationsPath = path8.join(projectRoot, config.translationsPath);
+  const sourceLanguage = config.sourceLanguage;
+  const sourceTranslations = readTranslations(translationsPath, sourceLanguage);
+  const sourceNamespaces = getNamespaces(translationsPath, sourceLanguage);
+  const languages = config.languages.filter((lang) => lang !== sourceLanguage);
+  const existedBefore = metadataExists(translationsPath);
+  const metadata = readMetadata(translationsPath);
+  let recorded = 0;
+  for (const language of languages) {
+    const targetTranslations = readTranslations(translationsPath, language);
+    for (const namespace of sourceNamespaces) {
+      const sourceKeys = sourceTranslations[namespace] || {};
+      const targetKeys = targetTranslations[namespace] || {};
+      for (const [key, sourceValue] of Object.entries(sourceKeys)) {
+        const targetValue = targetKeys[key];
+        const alreadyTranslated = typeof targetValue === "string" && targetValue.trim() !== "";
+        const alreadyTracked = getSourceHash(metadata, language, namespace, key) !== void 0;
+        if (alreadyTranslated && !alreadyTracked) {
+          setSourceHash(metadata, language, namespace, key, sourceValue);
+          recorded++;
+        }
+      }
+    }
+  }
+  if (recorded > 0) {
+    writeMetadata(translationsPath, metadata);
+  }
+  return { recorded, created: !existedBefore && recorded > 0 };
+}
 
 // src/translations/cli/auto-fill.ts
 async function processConcurrently(items, concurrency, processor) {
@@ -1969,10 +2147,31 @@ async function processConcurrently(items, concurrency, processor) {
   await Promise.all(executing);
   return results;
 }
+function getFillItemsForLanguage(projectRoot, translationsPath, sourceLanguage, language, options) {
+  if (options.force) {
+    const sourceTranslations = readTranslations(translationsPath, sourceLanguage);
+    const items = [];
+    for (const [namespace, keys] of Object.entries(sourceTranslations)) {
+      for (const [key, sourceValue] of Object.entries(keys)) {
+        items.push({ namespace, key, language, sourceValue, type: "forced" });
+      }
+    }
+    return items;
+  }
+  return getMissingForLanguage(projectRoot, language, { includeStale: options.retranslateChanged });
+}
 async function autoFillTranslations(projectRoot = process.cwd(), options = {}) {
   const config = loadConfig(projectRoot);
-  const translationsPath = path8.join(projectRoot, config.translationsPath);
-  const { apiKey, limit = Infinity, delayMs = 50, dryRun = false, concurrency = 5 } = options;
+  const translationsPath = path9.join(projectRoot, config.translationsPath);
+  const {
+    apiKey,
+    limit = Infinity,
+    delayMs = 50,
+    dryRun = false,
+    concurrency = 5,
+    retranslateChanged = false,
+    force = false
+  } = options;
   const currentProvider = getTranslationProvider();
   const isDefaultGoogleProvider = currentProvider.constructor.name === "GoogleTranslateProvider";
   if (isDefaultGoogleProvider) {
@@ -1995,14 +2194,17 @@ async function autoFillTranslations(projectRoot = process.cwd(), options = {}) {
     console.log(`Created ${syncResult.createdFiles.length} namespace files
 `);
   }
+  const mode = force ? "all keys (--force)" : retranslateChanged ? "missing, empty & changed" : "missing & empty";
   console.log("=====");
   console.log("Auto-filling translations");
   console.log("=====");
   console.log(`Languages: ${languagesToProcess.join(", ")}`);
+  console.log(`Mode: ${mode}`);
   console.log(`Limit: ${limit === Infinity ? "unlimited" : limit}`);
   console.log(`Concurrency: ${concurrency}`);
   console.log(`Dry run: ${dryRun}`);
   console.log("=====");
+  const metadata = readMetadata(translationsPath);
   let totalProcessed = 0;
   let totalTranslated = 0;
   for (const language of languagesToProcess) {
@@ -2013,9 +2215,12 @@ Reached limit of ${limit} translations`);
     }
     console.log(`
 Processing language: ${language}`);
-    const missing = getMissingForLanguage(projectRoot, language);
+    const missing = getFillItemsForLanguage(projectRoot, translationsPath, config.sourceLanguage, language, {
+      retranslateChanged,
+      force
+    });
     if (!missing.length) {
-      console.log("  No missing or empty translations");
+      console.log("  Nothing to translate");
       continue;
     }
     console.log(`  Found ${missing.length} translations to fill`);
@@ -2044,6 +2249,7 @@ Processing language: ${language}`);
           translations[item.namespace][item.key] = translated;
           const sorted = sortKeys(translations[item.namespace]);
           writeTranslation(translationsPath, language, item.namespace, sorted);
+          setSourceHash(metadata, language, item.namespace, item.key, item.sourceValue);
           console.log("    \u2713 Saved");
         } else {
           console.log("    \u2713 Dry run - not saved");
@@ -2059,6 +2265,9 @@ Processing language: ${language}`);
     });
     totalProcessed += itemsToProcess.length;
     totalTranslated += results.filter((r) => r.success).length;
+    if (!dryRun) {
+      writeMetadata(translationsPath, metadata);
+    }
   }
   console.log("\n=====");
   console.log(`Total processed: ${totalProcessed}`);
@@ -2073,12 +2282,22 @@ Processing language: ${language}`);
 init_generate_types();
 init_init();
 async function manageTranslations(projectRoot = process.cwd(), options = {}) {
-  const { autoFill = false, apiKey, limit, concurrency = 5, language, skipTypes = false, dryRun = false } = options;
+  const {
+    autoFill = false,
+    apiKey,
+    limit,
+    concurrency = 5,
+    language,
+    skipTypes = false,
+    dryRun = false,
+    retranslateChanged = false,
+    force = false
+  } = options;
   console.log("=====");
   console.log("Translation Management");
   console.log("=====");
-  const configPath = path9.join(projectRoot, ".translationsrc.json");
-  const isInitialized = fs5.existsSync(configPath);
+  const configPath = path10.join(projectRoot, ".translationsrc.json");
+  const isInitialized = fs6.existsSync(configPath);
   if (!isInitialized) {
     console.log("\u{1F4C1} No translation configuration found. Initializing...\n");
     initTranslations(projectRoot);
@@ -2087,9 +2306,9 @@ async function manageTranslations(projectRoot = process.cwd(), options = {}) {
     console.log("\u2713 Translation structure initialized\n");
   }
   const config = loadConfig(projectRoot);
-  const translationsPath = path9.join(projectRoot, config.translationsPath);
-  const sourceLangPath = path9.join(translationsPath, config.sourceLanguage);
-  if (!fs5.existsSync(sourceLangPath)) {
+  const translationsPath = path10.join(projectRoot, config.translationsPath);
+  const sourceLangPath = path10.join(translationsPath, config.sourceLanguage);
+  if (!fs6.existsSync(sourceLangPath)) {
     console.log(`\u26A0\uFE0F  Source language directory not found: ${sourceLangPath}`);
     console.log("Please add translation files to the source language directory.\n");
     return false;
@@ -2111,11 +2330,25 @@ async function manageTranslations(projectRoot = process.cwd(), options = {}) {
   if (syncResult.createdFiles.length === 0 && syncResult.cleanedKeys.length === 0 && syncResult.removedNamespaces.length === 0) {
     console.log("\u2713 Translation structure is already synchronized\n");
   }
+  if (!dryRun) {
+    const baseline = ensureBaselineMetadata(projectRoot);
+    if (baseline.recorded > 0) {
+      const verb = baseline.created ? "Created change-tracking baseline for" : "Added change tracking for";
+      console.log(`\u{1F4CC} ${verb} ${baseline.recorded} existing translations
+`);
+    }
+  }
   console.log("\u{1F50D} Validating translations...\n");
   const validationResult = validateTranslations(projectRoot);
-  if (validationResult.valid) {
+  const hasWorkToFill = !validationResult.valid || force || retranslateChanged && validationResult.stale.length > 0;
+  if (validationResult.valid && !validationResult.stale.length) {
     console.log("\n\u2705 All translations are complete!\n");
-  } else {
+  } else if (validationResult.valid) {
+    console.log(`
+\u26A0\uFE0F  ${validationResult.stale.length} translations may be outdated.
+`);
+  }
+  if (hasWorkToFill) {
     const totalMissing = validationResult.missing.length + validationResult.empty.length + validationResult.orphaned.length;
     if (autoFill) {
       if (!apiKey) {
@@ -2125,29 +2358,38 @@ async function manageTranslations(projectRoot = process.cwd(), options = {}) {
         console.log(`Set ${envVarName} or pass --api-key to enable auto-fill.
 `);
       } else {
-        console.log(`
-\u{1F916} Auto-filling ${totalMissing} missing translations...
+        if (force) {
+          console.log("\n\u{1F916} Force re-translating all keys...\n");
+        } else {
+          const staleCount = retranslateChanged ? validationResult.stale.length : 0;
+          console.log(`
+\u{1F916} Auto-filling ${totalMissing} missing and ${staleCount} changed translations...
 `);
+        }
         await autoFillTranslations(projectRoot, {
           apiKey,
           limit,
           concurrency,
           language,
           dryRun,
-          delayMs: 50
+          delayMs: 50,
+          retranslateChanged,
+          force
         });
         if (!dryRun) {
           console.log("\n\u{1F50D} Re-validating after auto-fill...\n");
           const revalidation = validateTranslations(projectRoot);
-          if (revalidation.valid) {
+          if (revalidation.valid && !revalidation.stale.length) {
             console.log("\n\u2705 All translations are now complete!\n");
           }
         }
       }
-    } else {
+    } else if (!validationResult.valid) {
       console.log(`
 \u{1F4A1} Tip: Run with --auto-fill to automatically translate missing keys.
 `);
+    } else if (validationResult.stale.length > 0) {
+      console.log("\n\u{1F4A1} Tip: Run with --auto-fill --retranslate-changed to update outdated translations.\n");
     }
   }
   if (!skipTypes && !dryRun) {
@@ -2173,9 +2415,17 @@ async function manageTranslations(projectRoot = process.cwd(), options = {}) {
     if (validationResult.orphaned.length > 0) {
       console.log(`\u26A0\uFE0F  ${validationResult.orphaned.length} orphaned translations (will be auto-removed on next sync)`);
     }
+    if (validationResult.stale.length > 0) {
+      console.log(`\u26A0\uFE0F  ${validationResult.stale.length} potentially outdated translations`);
+    }
     console.log("\nNext steps:");
     console.log("  1. Add missing translations manually, or");
     console.log("  2. Run with --auto-fill to translate automatically");
+  } else if (validationResult.valid && validationResult.stale.length > 0 && !autoFill) {
+    console.log(`
+\u26A0\uFE0F  ${validationResult.stale.length} potentially outdated translations`);
+    console.log("\nNext steps:");
+    console.log("  Run with --auto-fill --retranslate-changed to update them");
   } else if (validationResult.valid) {
     console.log("\n\u2705 All systems ready!");
   }
@@ -2219,6 +2469,14 @@ var { values, positionals } = parseArgs({
       short: "d",
       default: false
     },
+    "retranslate-changed": {
+      type: "boolean",
+      default: false
+    },
+    force: {
+      type: "boolean",
+      default: false
+    },
     namespace: {
       type: "string",
       short: "n"
@@ -2257,6 +2515,8 @@ Options (Smart Mode):
   -l, --language <lang>   Process only this language
   --limit <number>        Max translations to process (default: unlimited)
   --concurrency <number>  Number of concurrent translation requests (default: 5)
+  --retranslate-changed   Re-translate keys whose source value has changed since last run
+  --force                 Re-translate every key, even ones already translated
   --skip-types            Skip TypeScript type generation
   -d, --dry-run           Preview changes without saving
   -h, --help              Show this help
@@ -2287,6 +2547,12 @@ Examples:
   # Preview what would be translated (dry-run)
   translations --auto-fill --dry-run
 
+  # Re-translate keys whose source string changed since last run
+  translations --auto-fill --retranslate-changed
+
+  # Re-translate everything from scratch
+  translations --auto-fill --force
+
   # Add a new translation key (interactive mode)
   translations add
 
@@ -2341,8 +2607,8 @@ if (command === "find-unused") {
     (async () => {
       try {
         console.log("\n\u2728 Add a new translation key\n");
-        const configPath = path12.join(process.cwd(), ".translationsrc.json");
-        const isInitialized = fs7.existsSync(configPath);
+        const configPath = path13.join(process.cwd(), ".translationsrc.json");
+        const isInitialized = fs8.existsSync(configPath);
         if (!isInitialized) {
           console.log("\u26A0\uFE0F  Translation structure not initialized.");
           const shouldInit = await confirm2({
@@ -2358,7 +2624,7 @@ if (command === "find-unused") {
           }
         }
         const config = loadConfig(process.cwd());
-        const translationsPath = path12.join(process.cwd(), config.translationsPath);
+        const translationsPath = path13.join(process.cwd(), config.translationsPath);
         const existingNamespaces = getNamespaces(translationsPath, config.sourceLanguage);
         let namespace;
         if (existingNamespaces.length > 0) {
@@ -2479,23 +2745,26 @@ if (command === "find-unused") {
   console.log("Use --help for usage information");
   process.exit(1);
 } else {
-  const hasFlags = values["auto-fill"] || values.language || values["skip-types"] || values["dry-run"];
+  const hasFlags = values["auto-fill"] || values.language || values["skip-types"] || values["dry-run"] || values["retranslate-changed"] || values.force;
   if (hasFlags) {
-    const configPath = path12.join(process.cwd(), ".translationsrc.json");
-    const config = fs7.existsSync(configPath) ? loadConfig(process.cwd()) : { provider: "deepl" };
+    const configPath = path13.join(process.cwd(), ".translationsrc.json");
+    const config = fs8.existsSync(configPath) ? loadConfig(process.cwd()) : { provider: "deepl" };
     const provider = config.provider || "deepl";
     const envVarName = provider === "google" ? "GOOGLE_TRANSLATE_API_KEY" : "DEEPL_API_KEY";
     const apiKey = values["api-key"] || process.env[envVarName];
     const limit = values.limit ? Number.parseInt(values.limit, 10) : void 0;
     const concurrency = Number.parseInt(values.concurrency || "5", 10);
+    const autoFill = values["auto-fill"] || values["retranslate-changed"] || values.force;
     manageTranslations(process.cwd(), {
-      autoFill: values["auto-fill"],
+      autoFill,
       apiKey,
       limit,
       concurrency,
       language: values.language,
       skipTypes: values["skip-types"],
-      dryRun: values["dry-run"]
+      dryRun: values["dry-run"],
+      retranslateChanged: values["retranslate-changed"],
+      force: values.force
     }).then((isValid) => {
       if (!isValid) {
         process.exit(1);
@@ -2507,8 +2776,8 @@ if (command === "find-unused") {
   } else {
     (async () => {
       try {
-        const configPath = path12.join(process.cwd(), ".translationsrc.json");
-        const isInitialized = fs7.existsSync(configPath);
+        const configPath = path13.join(process.cwd(), ".translationsrc.json");
+        const isInitialized = fs8.existsSync(configPath);
         console.log("\n\u{1F30D} Translation Management\n");
         const action = await select2({
           message: "What would you like to do?",
@@ -2572,7 +2841,7 @@ if (command === "find-unused") {
             }
           }
           const config = loadConfig(process.cwd());
-          const translationsPath = path12.join(process.cwd(), config.translationsPath);
+          const translationsPath = path13.join(process.cwd(), config.translationsPath);
           const existingNamespaces = getNamespaces(translationsPath, config.sourceLanguage);
           let namespace;
           if (existingNamespaces.length > 0) {
@@ -2673,9 +2942,14 @@ if (command === "find-unused") {
             default: true
           });
           if (shouldContinue) {
+            const retranslateChanged = await confirm2({
+              message: "Also re-translate keys whose source value has changed?",
+              default: false
+            });
             await manageTranslations(process.cwd(), {
               autoFill: true,
-              apiKey
+              apiKey,
+              retranslateChanged
             });
           }
         } else if (action === "find-unused") {