poly-lexis 0.9.2 → 0.11.0

package/dist/index.js

@@ -431,6 +431,14 @@ var init_schema = __esm({
             type: "string"
           },
           default: [".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte"]
+        },
+        protectedTerms: {
+          type: "array",
+          description: "List of terms that should never be translated (e.g. brand names, technical terms)",
+          items: {
+            type: "string"
+          },
+          default: []
         }
       },
       required: ["translationsPath", "languages", "sourceLanguage"],
@@ -623,9 +631,99 @@ 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 path 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 path.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";
+    METADATA_FILE_NAME = ".translations-meta.json";
+    CURRENT_VERSION = 1;
+  }
+});
+
+// src/translations/utils/utils.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
 function flattenObject(obj, prefix = "") {
   const result = {};
   for (const [key, value] of Object.entries(obj)) {
@@ -658,16 +756,16 @@ function isNestedObject(obj) {
   return Object.values(obj).some((value) => typeof value === "object" && value !== null);
 }
 function readTranslations(translationsPath, language) {
-  const langPath = path.join(translationsPath, language);
-  if (!fs.existsSync(langPath)) {
+  const langPath = path2.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 = path.basename(file, ".json");
-    const filePath = path.join(langPath, file);
-    const content = fs.readFileSync(filePath, "utf-8");
+    const namespace = path2.basename(file, ".json");
+    const filePath = path2.join(langPath, file);
+    const content = fs2.readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(content);
     if (isNestedObject(parsed)) {
       translations[namespace] = flattenObject(parsed);
@@ -678,26 +776,26 @@ function readTranslations(translationsPath, language) {
   return translations;
 }
 function writeTranslation(translationsPath, language, namespace, translations) {
-  const langPath = path.join(translationsPath, language);
-  if (!fs.existsSync(langPath)) {
-    fs.mkdirSync(langPath, { recursive: true });
+  const langPath = path2.join(translationsPath, language);
+  if (!fs2.existsSync(langPath)) {
+    fs2.mkdirSync(langPath, { recursive: true });
   }
-  const filePath = path.join(langPath, `${namespace}.json`);
-  fs.writeFileSync(filePath, `${JSON.stringify(translations, null, 2)}
+  const filePath = path2.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 = path.join(translationsPath, language);
-  if (!fs.existsSync(langPath)) {
+  const langPath = path2.join(translationsPath, language);
+  if (!fs2.existsSync(langPath)) {
     return [];
   }
-  return fs.readdirSync(langPath).filter((f) => f.endsWith(".json")).map((f) => path.basename(f, ".json"));
+  return fs2.readdirSync(langPath).filter((f) => f.endsWith(".json")).map((f) => path2.basename(f, ".json"));
 }
 function hasInterpolation(text) {
   return /\{\{[^}]+\}\}/g.test(text);
@@ -724,13 +822,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 = path.join(translationsPath, lang);
-    if (!fs.existsSync(langPath)) {
-      fs.mkdirSync(langPath, { recursive: true });
+    const langPath = path2.join(translationsPath, lang);
+    if (!fs2.existsSync(langPath)) {
+      fs2.mkdirSync(langPath, { recursive: true });
     }
   }
 }
@@ -761,8 +859,8 @@ function syncTranslationStructure(translationsPath, languages, sourceLanguage) {
     const targetNamespaces = getNamespaces(translationsPath, language);
     for (const namespace of targetNamespaces) {
       if (!sourceNamespaces.includes(namespace)) {
-        const filePath = path.join(translationsPath, language, `${namespace}.json`);
-        fs.unlinkSync(filePath);
+        const filePath = path2.join(translationsPath, language, `${namespace}.json`);
+        fs2.unlinkSync(filePath);
         result.removedNamespaces.push({
           language,
           namespace,
@@ -771,9 +869,9 @@ function syncTranslationStructure(translationsPath, languages, sourceLanguage) {
       }
     }
     for (const namespace of sourceNamespaces) {
-      const filePath = path.join(translationsPath, language, `${namespace}.json`);
+      const filePath = path2.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 = {};
@@ -813,11 +911,22 @@ 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_metadata();
   }
 });
 
@@ -848,13 +957,13 @@ __export(init_exports, {
   initTranslations: () => initTranslations,
   loadConfig: () => loadConfig
 });
-import * as fs2 from "fs";
-import * as path2 from "path";
+import * as fs3 from "fs";
+import * as path3 from "path";
 function detectExistingTranslations(projectRoot) {
   const possiblePaths = ["public/static/locales", "public/locales", "src/locales", "locales", "i18n", "translations"];
   for (const possiblePath of possiblePaths) {
-    const fullPath = path2.join(projectRoot, possiblePath);
-    if (fs2.existsSync(fullPath)) {
+    const fullPath = path3.join(projectRoot, possiblePath);
+    if (fs3.existsSync(fullPath)) {
       const languages = getAvailableLanguages(fullPath);
       if (languages.length > 0) {
         return { path: possiblePath, languages };
@@ -884,7 +993,7 @@ function initTranslations(projectRoot, config = {}) {
       languages: validLanguages.length > 0 ? validLanguages : finalConfig.languages
     };
   }
-  const translationsPath = path2.join(projectRoot, finalConfig.translationsPath);
+  const translationsPath = path3.join(projectRoot, finalConfig.translationsPath);
   const languages = finalConfig.languages.length > 0 ? finalConfig.languages : [...DEFAULT_LANGUAGES];
   console.log(`Project root: ${projectRoot}`);
   console.log(`Translations path: ${translationsPath}`);
@@ -896,9 +1005,9 @@ function initTranslations(projectRoot, config = {}) {
   }
   ensureTranslationsStructure(translationsPath, languages);
   const sourceLanguage = finalConfig.sourceLanguage;
-  const sourcePath = path2.join(translationsPath, sourceLanguage);
-  const commonPath = path2.join(sourcePath, "common.json");
-  if (!fs2.existsSync(commonPath)) {
+  const sourcePath = path3.join(translationsPath, sourceLanguage);
+  const commonPath = path3.join(sourcePath, "common.json");
+  if (!fs3.existsSync(commonPath)) {
     const sampleTranslations = {
       LOADING: "Loading",
       SAVE: "Save",
@@ -907,7 +1016,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}`);
   }
@@ -921,8 +1030,8 @@ function initTranslations(projectRoot, config = {}) {
       console.log(`  ${lang}: ${langFiles.map((f) => f.namespace).join(", ")}`);
     }
   }
-  const configPath = path2.join(projectRoot, ".translationsrc.json");
-  if (!fs2.existsSync(configPath)) {
+  const configPath = path3.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,
@@ -931,7 +1040,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}`);
   }
@@ -940,8 +1049,8 @@ function initTranslations(projectRoot, config = {}) {
   console.log("=====");
 }
 function loadConfig(projectRoot) {
-  const configPath = path2.join(projectRoot, ".translationsrc.json");
-  if (!fs2.existsSync(configPath)) {
+  const configPath = path3.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}`);
@@ -953,7 +1062,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);
@@ -974,7 +1083,7 @@ var init_init = __esm({
 });
 
 // src/translations/cli/add-key.ts
-import * as path4 from "path";
+import * as path5 from "path";
 
 // src/translations/utils/deepl-translate-provider.ts
 init_language_fallback();
@@ -1180,6 +1289,9 @@ var GoogleTranslateProvider = class {
   }
 };
 
+// src/translations/cli/add-key.ts
+init_metadata();
+
 // src/translations/utils/translator.ts
 var defaultProvider = new GoogleTranslateProvider();
 var customProvider = null;
@@ -1215,8 +1327,8 @@ init_utils();
 init_utils();
 init_init();
 import { execSync } from "child_process";
-import * as fs3 from "fs";
-import * as path3 from "path";
+import * as fs4 from "fs";
+import * as path4 from "path";
 var PLURAL_SUFFIXES = ["_zero", "_one", "_two", "_few", "_many", "_other"];
 function extractPluralBaseKeys(keys) {
   const keySet = new Set(keys);
@@ -1249,11 +1361,11 @@ function generateTranslationTypes(projectRoot = process.cwd()) {
   console.log("Generating i18n types");
   console.log("=====");
   const config = loadConfig(projectRoot);
-  const translationsPath = path3.join(projectRoot, config.translationsPath);
+  const translationsPath = path4.join(projectRoot, config.translationsPath);
   const sourceLanguage = config.sourceLanguage;
-  const outputFilePath = path3.join(projectRoot, config.typesOutputPath);
-  const dirPath = path3.join(translationsPath, sourceLanguage);
-  if (!fs3.existsSync(dirPath)) {
+  const outputFilePath = path4.join(projectRoot, config.typesOutputPath);
+  const dirPath = path4.join(translationsPath, sourceLanguage);
+  if (!fs4.existsSync(dirPath)) {
     throw new Error(`Source language directory not found: ${dirPath}`);
   }
   const namespaces = getNamespaces(translationsPath, sourceLanguage);
@@ -1268,12 +1380,12 @@ function generateTranslationTypes(projectRoot = process.cwd()) {
   }
   const pluralBaseKeys = extractPluralBaseKeys(allKeys);
   allKeys = allKeys.concat(pluralBaseKeys);
-  const outputDir = path3.dirname(outputFilePath);
-  if (!fs3.existsSync(outputDir)) {
-    fs3.mkdirSync(outputDir, { recursive: true });
+  const outputDir = path4.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 {
@@ -1292,7 +1404,7 @@ function generateTranslationTypes(projectRoot = process.cwd()) {
 init_init();
 async function addTranslationKey(projectRoot, options) {
   const config = loadConfig(projectRoot);
-  const translationsPath = path4.join(projectRoot, config.translationsPath);
+  const translationsPath = path5.join(projectRoot, config.translationsPath);
   const { namespace, key, value, autoTranslate = false, apiKey } = options;
   const currentProvider = getTranslationProvider();
   const isDefaultGoogleProvider = currentProvider.constructor.name === "GoogleTranslateProvider";
@@ -1326,6 +1438,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);
@@ -1344,6 +1457,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 {
@@ -1353,6 +1467,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) {
@@ -1397,23 +1512,27 @@ async function addTranslationKeys(projectRoot, entries, autoTranslate = false, a
 }
 
 // src/translations/cli/auto-fill.ts
-import * as path6 from "path";
+import * as path7 from "path";
+init_metadata();
 init_utils();
 init_init();
 
 // src/translations/cli/validate.ts
+init_metadata();
 init_utils();
 init_init();
-import * as path5 from "path";
+import * as path6 from "path";
 function validateTranslations(projectRoot = process.cwd()) {
   const config = loadConfig(projectRoot);
-  const translationsPath = path5.join(projectRoot, config.translationsPath);
+  const translationsPath = path6.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) {
@@ -1450,6 +1569,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)) {
@@ -1465,7 +1595,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) {
@@ -1498,18 +1628,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 = path6.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) {
@@ -1532,10 +1717,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 = path6.join(projectRoot, config.translationsPath);
-  const { apiKey, limit = Infinity, delayMs = 50, dryRun = false, concurrency = 5 } = options;
+  const translationsPath = path7.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) {
@@ -1558,14 +1764,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) {
@@ -1576,9 +1785,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`);
@@ -1607,6 +1819,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");
@@ -1622,6 +1835,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}`);
@@ -1633,7 +1849,7 @@ Processing language: ${language}`);
 }
 async function fillNamespace(projectRoot, language, namespace, apiKey) {
   const config = loadConfig(projectRoot);
-  const translationsPath = path6.join(projectRoot, config.translationsPath);
+  const translationsPath = path7.join(projectRoot, config.translationsPath);
   const currentProvider = getTranslationProvider();
   const isDefaultGoogleProvider = currentProvider.constructor.name === "GoogleTranslateProvider";
   if (isDefaultGoogleProvider) {
@@ -1649,6 +1865,7 @@ async function fillNamespace(projectRoot, language, namespace, apiKey) {
   const targetTranslations = readTranslations(translationsPath, language);
   const sourceKeys = sourceTranslations[namespace] || {};
   const targetKeys = targetTranslations[namespace] || {};
+  const metadata = readMetadata(translationsPath);
   let count = 0;
   for (const [key, sourceValue] of Object.entries(sourceKeys)) {
     const targetValue = targetKeys[key];
@@ -1665,12 +1882,14 @@ async function fillNamespace(projectRoot, language, namespace, apiKey) {
       config.protectedTerms ?? []
     );
     targetKeys[key] = translated;
+    setSourceHash(metadata, language, namespace, key, sourceValue);
     count++;
     await new Promise((resolve) => setTimeout(resolve, 100));
   }
   if (count > 0) {
     const sorted = sortKeys(targetKeys);
     writeTranslation(translationsPath, language, namespace, sorted);
+    writeMetadata(translationsPath, metadata);
     console.log(`\u2713 Filled ${count} translations`);
   } else {
     console.log("No translations to fill");
@@ -1681,8 +1900,8 @@ async function fillNamespace(projectRoot, language, namespace, apiKey) {
 init_utils();
 init_init();
 import { execSync as execSync2, spawnSync } from "child_process";
-import * as fs4 from "fs";
-import * as path7 from "path";
+import * as fs5 from "fs";
+import * as path8 from "path";
 function isRipgrepAvailable() {
   try {
     execSync2("rg --version", { stdio: "ignore" });
@@ -1743,15 +1962,15 @@ function findFiles(rootDir, searchPaths, extensions) {
   ]);
   function scanDirectory(dir) {
     try {
-      const entries = fs4.readdirSync(dir, { withFileTypes: true });
+      const entries = fs5.readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
-        const fullPath = path7.join(dir, entry.name);
+        const fullPath = path8.join(dir, entry.name);
         if (entry.isDirectory()) {
           if (!excludeDirs.has(entry.name)) {
             scanDirectory(fullPath);
           }
         } else if (entry.isFile()) {
-          const ext = path7.extname(entry.name);
+          const ext = path8.extname(entry.name);
           if (extensionSet.has(ext)) {
             files.push(fullPath);
           }
@@ -1761,8 +1980,8 @@ function findFiles(rootDir, searchPaths, extensions) {
     }
   }
   for (const searchPath of searchPaths) {
-    const fullSearchPath = path7.join(rootDir, searchPath);
-    if (fs4.existsSync(fullSearchPath)) {
+    const fullSearchPath = path8.join(rootDir, searchPath);
+    if (fs5.existsSync(fullSearchPath)) {
       scanDirectory(fullSearchPath);
     }
   }
@@ -1770,7 +1989,7 @@ function findFiles(rootDir, searchPaths, extensions) {
 }
 function checkKeyInFile(key, filePath) {
   try {
-    const content = fs4.readFileSync(filePath, "utf-8");
+    const content = fs5.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)) {
@@ -1793,7 +2012,7 @@ function checkPartialMatches(key, files) {
   const foundParts = /* @__PURE__ */ new Set();
   for (const file of filesToCheck) {
     try {
-      const content = fs4.readFileSync(file, "utf-8");
+      const content = fs5.readFileSync(file, "utf-8");
       for (const part of significantParts) {
         if (foundParts.has(part)) continue;
         const partPattern = new RegExp(`\\b${part}\\b`, "gi");
@@ -1813,7 +2032,7 @@ function checkPartialMatches(key, files) {
 }
 function findUnusedKeys(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 searchPaths = config.searchPaths || ["src", "app", "pages", "components"];
   const searchExtensions = config.searchExtensions || [".ts", ".tsx", ".js", ".jsx", ".vue", ".svelte"];
@@ -1955,13 +2174,13 @@ init_init();
 init_schema();
 init_types();
 init_init();
-import * as fs5 from "fs";
-import * as path8 from "path";
+import * as fs6 from "fs";
+import * as path9 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 = path8.join(projectRoot, ".translationsrc.json");
-  const alreadyExists = fs5.existsSync(configPath);
+  const configPath = path9.join(projectRoot, ".translationsrc.json");
+  const alreadyExists = fs6.existsSync(configPath);
   if (alreadyExists) {
     console.log("\u26A0\uFE0F  Configuration file already exists at .translationsrc.json\n");
     const shouldOverwrite = await confirm({
@@ -2129,16 +2348,26 @@ function getLanguageName(code) {
 
 // src/translations/cli/manage.ts
 init_utils();
-import * as fs6 from "fs";
-import * as path9 from "path";
+import * as fs7 from "fs";
+import * as path10 from "path";
 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 = fs6.existsSync(configPath);
+  const configPath = path10.join(projectRoot, ".translationsrc.json");
+  const isInitialized = fs7.existsSync(configPath);
   if (!isInitialized) {
     console.log("\u{1F4C1} No translation configuration found. Initializing...\n");
     initTranslations(projectRoot);
@@ -2147,9 +2376,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 (!fs6.existsSync(sourceLangPath)) {
+  const translationsPath = path10.join(projectRoot, config.translationsPath);
+  const sourceLangPath = path10.join(translationsPath, config.sourceLanguage);
+  if (!fs7.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;
@@ -2171,11 +2400,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) {
@@ -2185,29 +2428,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) {
@@ -2233,9 +2485,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!");
   }
@@ -2250,6 +2510,7 @@ async function manageTranslations(projectRoot = process.cwd(), options = {}) {
 // src/translations/index.ts
 init_schema();
 init_types();
+init_metadata();
 init_utils();
 export {
   DEEPL_LANGUAGES,
@@ -2257,6 +2518,7 @@ export {
   DEFAULT_LANGUAGES,
   GOOGLE_LANGUAGES,
   GoogleTranslateProvider,
+  METADATA_FILE_NAME,
   SUPPORTED_LANGUAGES,
   TRANSLATION_CONFIG_SCHEMA,
   TRANSLATION_PROVIDERS,
@@ -2265,6 +2527,8 @@ export {
   autoFillTranslations,
   createEmptyTranslationStructure,
   detectExistingTranslations,
+  emptyMetadata,
+  ensureBaselineMetadata,
   ensureTranslationsStructure,
   extractPluralBaseKeys,
   extractVariables,
@@ -2274,11 +2538,14 @@ export {
   generateTranslationTypes,
   getAvailableLanguages,
   getFallbackMappings,
+  getMetadataPath,
   getMissingForLanguage,
   getNamespaces,
+  getSourceHash,
   getSupportedLanguages,
   getTranslationProvider,
   hasInterpolation,
+  hashSourceValue,
   initTranslations,
   initTranslationsInteractive,
   isNestedObject,
@@ -2289,10 +2556,14 @@ export {
   loadConfig,
   logLanguageFallback,
   manageTranslations,
+  metadataExists,
   printUnusedKeysResult,
+  pruneMetadata,
+  readMetadata,
   readTranslations,
   resetTranslationProvider,
   resolveLanguageWithFallback,
+  setSourceHash,
   setTranslationProvider,
   sortKeys,
   syncTranslationStructure,
@@ -2303,6 +2574,7 @@ export {
   validateLanguagesForProvider,
   validateTranslations,
   validateVariables,
+  writeMetadata,
   writeTranslation
 };
 //# sourceMappingURL=index.js.map