@babelize/engine 0.0.0-stage → 0.1.2

package/dist/modules/translator/translate.js

@@ -0,0 +1,1047 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FALLBACK_QA_WARNING = void 0;
+exports.loadProjectTranslationRules = loadProjectTranslationRules;
+exports.translateLocales = translateLocales;
+exports.backfillTranslationMemory = backfillTranslationMemory;
+const cache_keys_1 = require("../../utils/cache-keys");
+const untranslated_1 = require("../../utils/untranslated");
+const logger_1 = require("../../utils/logger");
+const translation_quality_1 = require("../../utils/translation-quality");
+const file_utils_1 = require("../../utils/file-utils");
+const placeholder_protection_1 = require("../../utils/placeholder-protection");
+const icu_message_1 = require("../../utils/icu-message");
+const keygen_1 = require("../keygen");
+const concurrent_map_1 = require("../../utils/concurrent-map");
+const language_codes_1 = require("./language-codes");
+const glossary_1 = require("../glossary");
+const check_project_1 = require("../../qa/check-project");
+const gemini_provider_1 = require("./client/gemini.provider");
+const memory_matcher_1 = require("./memory/memory-matcher");
+const default_translation_provider_1 = require("../../providers/default-translation-provider");
+const translation_sanitizer_1 = require("../../utils/translation-sanitizer");
+const glossary_match_1 = require("../../utils/glossary-match");
+const icu_spans_1 = require("../../utils/icu-spans");
+const icu_branches_1 = require("./icu-branches");
+const BATCH_SIZE = 15;
+/** QA note on keys the backup (NLLB) translator produced. */
+exports.FALLBACK_QA_WARNING = 'translated with the backup translator; will be retried with the AI translator next run';
+/** Keys re-sent after failing validation go in small batches with per-key notes. */
+const REPAIR_BATCH_SIZE = 5;
+const TRANSLATE_CONCURRENCY = 3; // Max concurrent locales/batches
+/**
+ * ICU branches sent to a plain-text translator go in requests of up to this
+ * many sentences (the translator service's batch limit).
+ */
+const BRANCH_BATCH_SIZE = 50;
+/** A plain source whose stored translation is ICU only fits a project whose runtime formats ICU. */
+function reusableTranslation(source, translated, targetPlurals) {
+    return targetPlurals || (0, icu_message_1.isIcuMessage)(source) || !(0, icu_message_1.isIcuMessage)(translated);
+}
+/** Per-entry instruction: pluralize a count argument if the target language needs it. */
+function pluralHint(args, targetLocale) {
+    const list = args.map((a) => `{${a}}`).join(', ');
+    return `${list} ${args.length === 1 ? 'is a number' : 'are numbers'}. If ${targetLocale} changes the words around it by number, return an ICU plural over it, e.g. {${args[0]}, plural, one {…} other {…}} with every ${targetLocale} plural category and "#" in each branch; otherwise keep ${list} as plain text. Keep every {argument} name and tag exactly.`;
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/**
+ * A full sentence (3+ real words) that came back identical to the source was
+ * not translated. Short strings ("OK", "Email", a product name) legitimately
+ * stay the same in many languages. Both arguments are the tokenized text, so
+ * placeholders and terms neither count as words nor hide a difference.
+ */
+function isUnchangedSentence(sentText, returnedText) {
+    const norm = (t) => t.replace(/\[\s*#\s*VAR_\d+\s*#\s*\]/gi, ' ').replace(/\s+/g, ' ').trim().toLowerCase();
+    const words = norm(sentText).split(' ').filter((w) => /\p{L}{2,}/u.test(w));
+    return words.length >= 3 && norm(sentText) === norm(returnedText);
+}
+/** Tags, URLs, code and never-translate terms present in the source but absent from the output. */
+function missingSpans(source, translated, neverTranslateTerms) {
+    const have = new Set((0, placeholder_protection_1.protectText)(translated, neverTranslateTerms, { icu: true }).tokens.map((t) => t.toLowerCase()));
+    const want = new Set((0, placeholder_protection_1.protectText)(source, neverTranslateTerms, { icu: true }).tokens);
+    return [...want].filter((t) => !have.has(t.toLowerCase()));
+}
+/** Glossary terms in the source whose required translation is missing from the output. */
+function glossaryWarnings(source, translated, glossary, neverTranslateTerms) {
+    return glossary
+        .filter((g) => (0, glossary_1.sourceHasTerm)(source, g.term, neverTranslateTerms) && !(0, glossary_match_1.containsGlossaryTranslation)(translated, g.translation))
+        .map((g) => `Glossary: "${g.term}" should be translated as "${g.translation}"`);
+}
+/**
+ * Why a stored translation (cache or TM) can't be reused under the project's
+ * current glossary, or null if it can: a placeholder, tag, URL or
+ * never-translate term of the source is missing, or an "always translate as"
+ * term's required translation is. Such a hit is treated as a miss.
+ */
+function storedTranslationProblem(source, stored, neverTranslateTerms, glossaryForLocale) {
+    const lost = missingSpans(source, stored, neverTranslateTerms);
+    if (lost.length > 0)
+        return `missing ${lost.join(', ')}`;
+    const glossary = glossaryWarnings(source, stored, glossaryForLocale, neverTranslateTerms);
+    return glossary.length > 0 ? glossary.join('; ') : null;
+}
+const SCRIPT_RANGES = [
+    [0x0000, 0x024F], // Latin (Basic, Latin-1, Extended-A/B) — one script
+    [0x0370, 0x03FF], // Greek
+    [0x0400, 0x04FF], // Cyrillic
+    [0x0590, 0x05FF], // Hebrew
+    [0x0600, 0x06FF], // Arabic
+    [0x0900, 0x097F], // Devanagari
+    [0x0980, 0x09FF], // Bengali
+    [0x0E00, 0x0E7F], // Thai
+    [0x1100, 0x11FF], // Hangul Jamo
+    [0x3040, 0x309F], // Hiragana
+    [0x30A0, 0x30FF], // Katakana
+    [0x4E00, 0x9FFF], // CJK Unified
+    [0xAC00, 0xD7AF], // Hangul Syllables
+];
+function detectScript(ch) {
+    const code = ch.codePointAt(0);
+    for (let i = 0; i < SCRIPT_RANGES.length; i++) {
+        if (code >= SCRIPT_RANGES[i][0] && code <= SCRIPT_RANGES[i][1])
+            return i;
+    }
+    return -1;
+}
+/**
+ * True when the text's letters come from more than one writing system
+ * (e.g. "Hello 世界"). Only letters count: "Café", "© 2024", "10 °C" and
+ * non-breaking spaces are plain Latin text.
+ */
+function hasMixedScripts(text) {
+    let seen = -1;
+    for (const ch of text) {
+        if (!/\p{L}/u.test(ch))
+            continue;
+        const script = detectScript(ch);
+        if (script === -1)
+            continue;
+        if (seen === -1) {
+            seen = script;
+        }
+        else if (script !== seen) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Load a project's glossary and brand voice. Never throws: a failure means
+ * translating without that rule, as before. The two lookups are independent,
+ * so a glossary failure doesn't also drop the brand voice. `complete` is false
+ * if either failed — callers that copy text into shared TM must then assume
+ * project-specific wording may be baked in.
+ */
+async function loadProjectTranslationRules(projectId, rules) {
+    let glossary = glossary_1.EMPTY_GLOSSARY;
+    let brandVoice = null;
+    let complete = true;
+    if (!rules)
+        return { glossary, brandVoice, complete };
+    try {
+        const entries = await rules.getGlossary(projectId);
+        if (entries?.length) {
+            glossary = (0, glossary_1.normalizeGlossary)(entries);
+            logger_1.engineLogger.info('Loaded project glossary', {
+                neverTranslate: glossary.neverTranslate.length,
+                alwaysTranslateAs: glossary.alwaysTranslateAs.length,
+                conflicts: glossary.conflicts.length,
+            });
+            for (const c of glossary.conflicts)
+                logger_1.engineLogger.warn(c.message, { projectId });
+        }
+    }
+    catch (err) {
+        complete = false;
+        logger_1.engineLogger.warn('Failed to load glossary entries', { error: err });
+    }
+    try {
+        brandVoice = await rules.getBrandVoice(projectId);
+        if (brandVoice) {
+            logger_1.engineLogger.info('Brand voice configured', {
+                length: brandVoice.length,
+                hash: (0, cache_keys_1.hashText)(brandVoice),
+            });
+        }
+    }
+    catch (err) {
+        complete = false;
+        logger_1.engineLogger.warn('Failed to load brand voice', { error: err });
+    }
+    return { glossary, brandVoice, complete };
+}
+/**
+ * The glossary of a run without a cloud project (CLI/MCP, no projectId):
+ * `.babelize/config.json` `glossary`, the same file and schema `babelize
+ * check` reads.
+ */
+async function loadWorkspaceGlossary(workspacePath) {
+    try {
+        const { glossary } = await (0, check_project_1.readProjectLocaleConfig)(workspacePath);
+        if (!glossary)
+            return glossary_1.EMPTY_GLOSSARY;
+        const rules = (0, glossary_1.normalizeGlossary)([
+            ...(glossary.neverTranslate ?? []).map((term) => ({ term, type: 'never_translate' })),
+            ...(glossary.alwaysTranslateAs ?? []).map((e) => ({ term: e.term, type: 'always_translate_as', translations: e.translations })),
+        ]);
+        logger_1.engineLogger.info('Loaded glossary from workspace config', {
+            neverTranslate: rules.neverTranslate.length,
+            alwaysTranslateAs: rules.alwaysTranslateAs.length,
+        });
+        return rules;
+    }
+    catch (err) {
+        logger_1.engineLogger.warn('Failed to load glossary from workspace config', { error: err });
+        return glossary_1.EMPTY_GLOSSARY;
+    }
+}
+async function translateLocales(workspace, sourceLocale, targetLocales, forceTranslation = false, dryRun = false, projectId, onProgress, keysToTranslateByLocale, cacheProvider, byokConfig, contextMap, extractionContextMap, providers = {}, options = {}) {
+    const locales = [];
+    const errors = [];
+    const failures = [];
+    let tmHitsTotal = 0;
+    const perLocaleMetadata = {};
+    // Ensure locale output directories exist for all target locales
+    if (!dryRun) {
+        for (const locale of targetLocales) {
+            const { dir } = (0, file_utils_1.localeFilePath)(workspace.path, workspace.publicDir, workspace.localeFormat, locale);
+            await (0, file_utils_1.ensureDir)(dir);
+        }
+    }
+    const flatSource = (0, keygen_1.flattenLocaleData)(sourceLocale.data);
+    // Strip _meta.* entries from flatSource so meta fields are never sent to the
+    // translation engine, never stored in the lockfile, and never overwrite the
+    // target locale's own computed _meta values.
+    for (const key of Object.keys(flatSource)) {
+        if (key === '_meta' || key.startsWith('_meta.')) {
+            delete flatSource[key];
+        }
+    }
+    // The project's glossary and brand voice (injected rules store), or for a
+    // run without a project the workspace's .babelize/config.json glossary.
+    const rules = options.rules
+        ?? (projectId
+            ? await loadProjectTranslationRules(projectId, providers.rules)
+            : { glossary: await loadWorkspaceGlossary(workspace.path), brandVoice: null, complete: true });
+    const glossary = rules.glossary;
+    const neverTranslateTerms = glossary.neverTranslate;
+    const brandVoice = rules.brandVoice;
+    const rulesComplete = rules.complete;
+    // Check if translator is configured before processing locales
+    if (!byokConfig && !providers.translator && !process.env.TRANSLATOR_URL && targetLocales.some(l => l !== sourceLocale.locale)) {
+        logger_1.engineLogger.error('TRANSLATOR_URL environment variable is not set and no BYOK config provided. Translations will fall back to source text.');
+    }
+    const localeTasks = targetLocales
+        .filter((l) => l !== sourceLocale.locale && (0, language_codes_1.isSupported)(l));
+    const { results: localeResults, errors: localeErrors } = await (0, concurrent_map_1.concurrentMap)(localeTasks, async (targetLocale) => {
+        const targetLangCode = (0, language_codes_1.toFlores)(targetLocale);
+        const localePaths = (0, file_utils_1.localeFilePath)(workspace.path, workspace.publicDir, workspace.localeFormat, targetLocale);
+        const targetPath = localePaths.file;
+        const relativePath = localePaths.relativeFile;
+        let entriesToTranslate = flatSource;
+        if (keysToTranslateByLocale && keysToTranslateByLocale[targetLocale]) {
+            entriesToTranslate = {};
+            for (const key of keysToTranslateByLocale[targetLocale]) {
+                if (flatSource[key]) {
+                    entriesToTranslate[key] = flatSource[key];
+                }
+            }
+        }
+        if (Object.keys(entriesToTranslate).length === 0) {
+            return {
+                locale: targetLocale,
+                file: { locale: targetLocale, path: relativePath, data: {}, isNew: true },
+                tmHits: 0,
+                metadata: {},
+                failures: {},
+                error: null,
+            };
+        }
+        const sourceLangCode = (0, language_codes_1.toFlores)(sourceLocale.locale);
+        // LLM translators (BYOK, or an injected one such as Babelize-hosted)
+        // take the brand voice in the prompt; NLLB output is polished after.
+        const hasBrandVoiceInPrompt = !!((byokConfig || (providers.translator && !providers.translator.plainText)) && brandVoice);
+        const translationResult = await translateEntries(entriesToTranslate, sourceLangCode, targetLangCode, projectId, onProgress, glossary, targetLocale, cacheProvider, byokConfig, contextMap, extractionContextMap, hasBrandVoiceInPrompt ? (brandVoice || undefined) : undefined, dryRun, forceTranslation, providers, rulesComplete, options);
+        const entriesResult = translationResult.result;
+        const batchStats = translationResult.stats;
+        const batchMetadata = translationResult.metadata;
+        const keyFailures = translationResult.failures;
+        if (Object.keys(entriesResult).length === 0 && Object.keys(entriesToTranslate).length > 0) {
+            // Nothing translated: write no file. Every key is in keyFailures with
+            // its reason, so the caller can report exactly what went wrong.
+            logger_1.engineLogger.error(`No strings could be translated for locale "${targetLocale}"`, {
+                locale: targetLocale, sourceKeys: Object.keys(entriesToTranslate).length,
+            });
+            return { locale: targetLocale, file: null, tmHits: batchStats.tmHits, metadata: batchMetadata, failures: keyFailures, error: null };
+        }
+        let translatedEntries = entriesResult;
+        // Post-hoc brand voice polish only for the NLLB service; LLM
+        // translators already had the brand voice in the prompt.
+        const glossaryForLocale = (0, glossary_1.fixedTermsFor)(glossary, targetLocale);
+        if (brandVoice && !hasBrandVoiceInPrompt) {
+            // TM hits are approved/previously-accepted text: polishing them again
+            // would rewrite reviewed translations nondeterministically every run.
+            const toPolish = {};
+            for (const [k, v] of Object.entries(translatedEntries)) {
+                if (!batchMetadata[k]?.fromMemory)
+                    toPolish[k] = v;
+            }
+            if (Object.keys(toPolish).length > 0) {
+                const polished = await (0, gemini_provider_1.polishWithBrandVoice)(toPolish, brandVoice, targetLocale);
+                if (polished !== toPolish) {
+                    // The polish is a free rewrite of already-validated text: keep a
+                    // rewrite only if it still has exactly the same placeholders, tags
+                    // and terms (and, for ICU, is still a valid equivalent message).
+                    const accepted = {};
+                    let rejected = 0;
+                    for (const [k, v] of Object.entries(polished)) {
+                        const before = toPolish[k];
+                        if (before === undefined || typeof v !== 'string' || !v.trim())
+                            continue;
+                        // ICU (in the source, or a plural the translation added) must
+                        // stay an equivalent message of the validated translation.
+                        const icu = (0, icu_message_1.isIcuMessage)(entriesToTranslate[k] ?? '') || (0, icu_message_1.isIcuMessage)(before) || (0, icu_message_1.isIcuMessage)(v);
+                        // ...and still uses every required glossary translation the validated text used.
+                        const source = entriesToTranslate[k] ?? '';
+                        const glossaryOk = glossaryWarnings(source, v, glossaryForLocale, neverTranslateTerms).length <= glossaryWarnings(source, before, glossaryForLocale, neverTranslateTerms).length;
+                        const safe = (0, placeholder_protection_1.sameProtectedSpans)(before, v, neverTranslateTerms) && glossaryOk &&
+                            (!icu || !(0, icu_message_1.compareIcuMessages)(before, v, targetLocale).some((i) => i.severity === 'error'));
+                        if (safe)
+                            accepted[k] = v;
+                        else
+                            rejected++;
+                    }
+                    logger_1.engineLogger.info('Brand voice polish applied', { locale: targetLocale, accepted: Object.keys(accepted).length, rejected });
+                    translatedEntries = { ...translatedEntries, ...accepted };
+                }
+            }
+        }
+        let translatedData = (0, keygen_1.unflattenLocaleData)(translatedEntries);
+        const existingTranslatedMeta = typeof translatedData._meta === 'object' && translatedData._meta !== null
+            ? translatedData._meta
+            : {};
+        translatedData = {
+            ...translatedData,
+            _meta: { ...existingTranslatedMeta, dir: (0, language_codes_1.isRTL)(targetLocale) ? 'rtl' : 'ltr', language: targetLocale },
+        };
+        // gettext catalogues are merged into the existing .po files once the
+        // whole run's translations are known (see django/catalog.ts).
+        if (!dryRun && workspace.localeFormat !== 'po')
+            await (0, file_utils_1.writeJsonFile)(targetPath, translatedData, true);
+        return {
+            locale: targetLocale,
+            file: {
+                locale: targetLocale,
+                path: relativePath,
+                data: translatedData,
+                isNew: true,
+                isRTL: (0, language_codes_1.isRTL)(targetLocale),
+            },
+            tmHits: batchStats.tmHits,
+            metadata: batchMetadata,
+            failures: keyFailures,
+            error: null,
+        };
+    }, TRANSLATE_CONCURRENCY);
+    for (const r of localeResults) {
+        if (!r)
+            continue;
+        for (const [key, f] of Object.entries(r.failures ?? {})) {
+            failures.push({ locale: r.locale, key, source: flatSource[key] ?? '', ...f });
+        }
+        if (r.error) {
+            errors.push({ locale: r.locale, error: r.error });
+        }
+        else if (r.file) {
+            locales.push(r.file);
+            tmHitsTotal += r.tmHits;
+            perLocaleMetadata[r.locale] = r.metadata;
+        }
+    }
+    // Collect errors from unsupported locales
+    for (const targetLocale of targetLocales) {
+        if (targetLocale === sourceLocale.locale)
+            continue;
+        if (!(0, language_codes_1.isSupported)(targetLocale)) {
+            errors.push({ locale: targetLocale, error: `Unsupported language code: ${targetLocale}` });
+        }
+    }
+    // Fail immediately when BYOK translation errors occurred
+    if (byokConfig && (errors.length > 0 || localeErrors.length > 0)) {
+        throw localeErrors.length > 0 ? localeErrors[0] : new Error(errors[0].error);
+    }
+    return {
+        translation: { locales, errors, failures },
+        stats: { tmHits: tmHitsTotal },
+        metadata: perLocaleMetadata
+    };
+}
+async function translateEntries(entries, sourceLang, targetLang, projectId, onProgress, glossary = glossary_1.EMPTY_GLOSSARY, targetLocale = '', cacheProvider, byokConfig, contextMap, extractionContextMap, brandVoice, dryRun = false, forceTranslation = false, providers = {}, rulesComplete = true, options = {}) {
+    const result = {};
+    const metadata = {};
+    const keys = Object.keys(entries);
+    // Cache and TM key: the FLORES code, plus the region for regional variants
+    // (pt-BR vs pt-PT share por_Latn but must not share translations).
+    const storeLang = targetLocale && (0, language_codes_1.isSupported)(targetLocale) ? (0, language_codes_1.storageLangCode)(targetLocale) : targetLang;
+    let uncachedEntries = [];
+    let cacheHits = 0;
+    let tmHits = 0;
+    const cacheBackfill = [];
+    const markInTm = (keys) => {
+        for (const k of keys)
+            metadata[k] = { ...(metadata[k] ?? {}), inTm: true };
+    };
+    const neverTranslateTerms = glossary.neverTranslate;
+    // "Always translate as" terms with a translation for this locale (exact
+    // locale, else its base language).
+    const glossaryForLocale = (0, glossary_1.fixedTermsFor)(glossary, targetLocale);
+    // Output shaped by such a rule is this project's wording: it must not go
+    // into the cache or TM, which are shared beyond the project.
+    const projectWording = (source) => (0, glossary_1.hasFixedTerm)(source, glossary, targetLocale);
+    const reuseProblem = (source, stored) => storedTranslationProblem(source, stored, neverTranslateTerms, glossaryForLocale);
+    for (const key of keys) {
+        const text = entries[key];
+        const entryContext = contextMap?.[key];
+        const textForHash = entryContext ? `${text}:::${entryContext}` : text;
+        const textHash = (0, cache_keys_1.hashText)(textForHash);
+        const cacheKey = (0, cache_keys_1.translationCacheKey)(sourceLang, storeLang, textHash);
+        const cached = cacheProvider && !forceTranslation ? await cacheProvider.get(cacheKey) : { hit: false, data: null };
+        // A stored value that is the untranslated source (cached before this was
+        // rejected) is a miss, so the string is translated again instead of failing forever.
+        // So is one that breaks the project's glossary (a never-translate term
+        // translated, a required translation missing): glossary edits reach
+        // cached strings by re-translating them.
+        const cacheProblem = cached.hit && cached.data !== null ? reuseProblem(text, cached.data) : null;
+        if (cacheProblem)
+            logger_1.engineLogger.info('Cached translation breaks the glossary; translating again', { key, targetLocale, problem: cacheProblem });
+        if (cached.hit && cached.data !== null && !cacheProblem && reusableTranslation(text, cached.data, !!options.targetPlurals) && !(0, untranslated_1.isUntranslatedInto)(text, cached.data, targetLocale)) {
+            result[key] = cached.data;
+            cacheHits++;
+            // Reused, not translated this run (billing counts only fresh output).
+            metadata[key] = { ...(metadata[key] ?? {}), fromCache: true };
+            // Keep out of shared TM: sentence fragments (context-dependent), and —
+            // since cache entries written before TM stored pre-glossary text may
+            // have them baked in — strings with project glossary rules or an
+            // in-prompt brand voice, which must not leak into other projects.
+            if (rulesComplete && !entryContext && !brandVoice && !projectWording(text)) {
+                cacheBackfill.push({ key, sourceText: text, translatedText: cached.data });
+            }
+        }
+        else {
+            uncachedEntries.push({ key, value: text, hash: textHash, context: entryContext });
+        }
+    }
+    const memory = providers.memory;
+    const translator = providers.translator ?? (0, default_translation_provider_1.createDefaultTranslationProvider)(byokConfig);
+    let tmContext = null;
+    if (projectId && memory) {
+        try {
+            tmContext = await memory.getProjectContext(projectId);
+        }
+        catch (err) {
+            logger_1.engineLogger.error('Failed to resolve TM owner; TM disabled for this locale', { projectId, error: err });
+        }
+    }
+    const ownerId = memory ? tmContext?.ownerId ?? null : null;
+    if (cacheBackfill.length > 0 && projectId && tmContext && !dryRun) {
+        // Redis hits never reach the translator, so without this a re-run would
+        // never populate TM for strings translated before TM writes worked.
+        if (await persistToTM(memory, cacheBackfill, projectId, tmContext, sourceLang, storeLang, { overwrite: false })) {
+            markInTm(cacheBackfill.map((i) => i.key));
+        }
+    }
+    // When the TM lookup fails we can't tell which strings already have a
+    // (possibly human-edited) TM entry, so later writes must not overwrite.
+    let tmLookupFailed = false;
+    // Source texts whose TM entry a human approved: a forced re-translate still
+    // uses fresh output for this run but must not overwrite those entries.
+    const approvedSourceTexts = new Set();
+    if (forceTranslation && ownerId && projectId && !dryRun && uncachedEntries.length > 0) {
+        try {
+            const existing = await memory.getAllForOwner(ownerId, sourceLang, storeLang);
+            for (const m of existing)
+                if (m.approvedAt)
+                    approvedSourceTexts.add(m.sourceText);
+        }
+        catch (err) {
+            tmLookupFailed = true;
+            logger_1.engineLogger.error('Failed to read Translation Memory before forced re-translate; TM writes will not overwrite', { error: err });
+        }
+    }
+    if (uncachedEntries.length > 0 && ownerId && !forceTranslation) {
+        try {
+            logger_1.engineLogger.info('Checking Memory for entries', {
+                count: uncachedEntries.length,
+                ownerId,
+                targetLocale,
+            });
+            // 1. Fetch all TM for owner (for fuzzy matching)
+            // TM rows store FLORES codes (eng_Latn → fra_Latn), so look up by the
+            // FLORES codes, not the ISO locale.
+            const allMemory = await memory.getAllForOwner(ownerId, sourceLang, storeLang);
+            const stillUncached = [];
+            for (const entry of uncachedEntries) {
+                // TM is context-free; a sentence fragment's translation depends on
+                // the sentence around it, so never auto-apply TM to one.
+                if (entry.context) {
+                    stillUncached.push(entry);
+                    continue;
+                }
+                const lookup = (0, memory_matcher_1.matchFromMemory)(allMemory, entry.value, storeLang);
+                // A TM entry that breaks this project's glossary is a miss (TM is shared across the owner's projects).
+                const tmProblem = lookup.hit && lookup.translatedText ? reuseProblem(entry.value, lookup.translatedText) : null;
+                if (tmProblem)
+                    logger_1.engineLogger.info('TM translation breaks the glossary; translating again', { key: entry.key, targetLocale, problem: tmProblem });
+                if (lookup.hit && lookup.translatedText && !tmProblem && reusableTranslation(entry.value, lookup.translatedText, !!options.targetPlurals) && !(0, untranslated_1.isUntranslatedInto)(entry.value, lookup.translatedText, targetLocale)) {
+                    result[entry.key] = lookup.translatedText;
+                    tmHits++;
+                    metadata[entry.key] = { fromMemory: true, inTm: true };
+                    // Warm the cache (never with this project's glossary wording)
+                    const cacheKey = (0, cache_keys_1.translationCacheKey)(sourceLang, storeLang, entry.hash);
+                    if (cacheProvider && !projectWording(entry.value)) {
+                        cacheProvider.set(cacheKey, lookup.translatedText, cache_keys_1.TRANSLATION_CACHE_TTL_SECONDS).catch((err) => {
+                            logger_1.engineLogger.error('Failed to warm Redis cache from TM', { cacheKey, error: err });
+                        });
+                    }
+                }
+                else if (lookup.fuzzyMatches && lookup.fuzzyMatches.length > 0) {
+                    // Store fuzzy matches as metadata so they can be surfaced as suggestions in dashboard
+                    metadata[entry.key] = { fuzzyMatches: lookup.fuzzyMatches };
+                    stillUncached.push(entry);
+                }
+                else {
+                    stillUncached.push(entry);
+                }
+            }
+            uncachedEntries = stillUncached;
+        }
+        catch (err) {
+            tmLookupFailed = true;
+            logger_1.engineLogger.error('Failed to query Translation Memory; new TM writes will not overwrite existing entries', { error: err });
+        }
+    }
+    if (keys.length > 0) {
+        const hitRate = Math.round(((cacheHits + tmHits) / keys.length) * 100);
+        logger_1.engineLogger.info('Translation cache stats', {
+            cacheHits,
+            tmHits,
+            total: keys.length,
+            hitRate,
+            toTranslate: uncachedEntries.length,
+        });
+    }
+    const failures = {};
+    // LLM providers get structure-aware prompts and repair attempts. The NLLB
+    // service translates plain text only: ICU messages go branch by branch
+    // (./icu-branches), and mixed-script text fails up front.
+    const isLlm = !!byokConfig || (!!providers.translator && !providers.translator.plainText);
+    // Scripts FLORES-200 lacks (sr-Latn, uz-Cyrl) only work with an LLM.
+    const nllbTarget = !targetLocale || !(0, language_codes_1.isSupported)(targetLocale) || (0, language_codes_1.isNllbSupported)(targetLocale);
+    if (uncachedEntries.length > 0) {
+        // 1. Protect placeholders, tags and never-translate terms. Strings with
+        //    nothing translatable left (e.g. "{count}", a brand name) are their own
+        //    translation and never reach the translator. "Always translate as"
+        //    terms are tokens too for a plain-text translator, restored to their
+        //    fixed translation (it can't take a glossary); an LLM gets them as
+        //    required terminology in the prompt instead.
+        const prepared = [];
+        for (const entry of uncachedEntries) {
+            const icu = (0, icu_message_1.isIcuMessage)(entry.value);
+            if (!isLlm && (hasMixedScripts(entry.value) || !nllbTarget)) {
+                failures[entry.key] = {
+                    reason: 'unsupported_by_provider',
+                    retryable: false,
+                    message: !nllbTarget
+                        ? `${targetLocale} needs an LLM translation provider`
+                        : 'Text mixing writing systems needs an LLM translation provider',
+                };
+                continue;
+            }
+            // ICU branches legitimately repeat or drop spans (Polish adds branches,
+            // Japanese keeps only "other"), so ICU text is sent untokenized and its
+            // tags/URLs/terms are checked as a set after translation instead. The
+            // same goes for a plain message with a count ("{files} files were
+            // uploaded"): an LLM may return a plural for a language that needs one;
+            // for NLLB one is built branch by branch when the language has more
+            // than one plural category.
+            const countArgs = options.targetPlurals && !icu && (isLlm || (0, icu_branches_1.targetCategories)(targetLocale, 'cardinal').length > 1)
+                ? (0, icu_message_1.countArguments)(entry.value)
+                : [];
+            const ownTokens = (0, placeholder_protection_1.protectText)(entry.value, neverTranslateTerms);
+            if ((0, placeholder_protection_1.hasNothingToTranslate)(ownTokens.text)) {
+                result[entry.key] = entry.value;
+                // Copied through (placeholders/codes only); the translator never saw it.
+                metadata[entry.key] = { ...(metadata[entry.key] ?? {}), passthrough: true };
+                continue;
+            }
+            // Never-translate terms win over a fixed term spelled the same, and
+            // placeholders/URLs/tags over both (see protectText).
+            const withFixed = glossaryForLocale.length > 0
+                ? (0, placeholder_protection_1.protectText)(entry.value, neverTranslateTerms, { fixedTerms: glossaryForLocale })
+                : ownTokens;
+            if (!icu && (0, placeholder_protection_1.hasNothingToTranslate)(withFixed.text)) {
+                // Only glossary terms and placeholders ("Settings" → "Konfiguration"):
+                // the rule is the translation; no translator needed (or billed).
+                result[entry.key] = (0, placeholder_protection_1.restoreText)(withFixed.text, withFixed.restore);
+                metadata[entry.key] = { ...(metadata[entry.key] ?? {}), passthrough: true, glossary: true };
+                continue;
+            }
+            const tokenized = isLlm ? ownTokens : withFixed;
+            const sendRaw = icu || countArgs.length > 0;
+            const prot = sendRaw ? { text: entry.value, tokens: [], restore: [] } : tokenized;
+            prepared.push({
+                ...entry,
+                sendText: prot.text,
+                tokens: prot.tokens,
+                restore: prot.restore,
+                icu: sendRaw,
+                countArgs: countArgs.length ? countArgs : undefined,
+                plain: countArgs.length || (isLlm && !icu)
+                    ? { sendText: withFixed.text, tokens: withFixed.tokens, restore: withFixed.restore }
+                    : undefined,
+            });
+        }
+        // 2. Translate in batches; judge every key independently.
+        const outcomes = new Map();
+        const judge = (entry, keyResult, nllb = !isLlm) => {
+            const fail = (reason, retryable, message) => ({ ok: false, reason, retryable, message });
+            if (!keyResult)
+                return fail('missing_from_response', true, 'The translator returned no translation for this string');
+            if (keyResult.status === 'failed') {
+                return fail(keyResult.reason, keyResult.retryable, keyResult.message ?? `Translator reported ${keyResult.reason}`);
+            }
+            if (!keyResult.value.trim())
+                return fail('empty_value', true, 'The translator returned an empty string');
+            // A plain source must stay plain unless a plural was allowed for it.
+            if (!(0, icu_message_1.isIcuMessage)(entry.value) && !entry.countArgs && (0, icu_message_1.isIcuMessage)(keyResult.value)) {
+                const args = (0, icu_message_1.extractSimpleArguments)(entry.value);
+                return fail('icu_invalid', true, `The source is plain text: return plain text, not ICU plural/select syntax${args.length ? `, and keep ${args.map((a) => `{${a}}`).join(', ')} as is` : ''}`);
+            }
+            const tokenCheck = (0, placeholder_protection_1.checkTokens)(keyResult.value, entry.tokens.length);
+            if (!tokenCheck.ok)
+                return fail('placeholder_lost', true, `Placeholder problem: ${(0, placeholder_protection_1.describeTokenProblem)(tokenCheck, entry.tokens)}`);
+            const value = (0, placeholder_protection_1.restoreText)((0, translation_sanitizer_1.sanitizeTranslation)(keyResult.value, { nllb, source: entry.sendText }), entry.restore);
+            // NLLB sometimes answers a short string with only its language tag
+            // ("eng_Latn"), which the sanitizer strips to nothing: no translation.
+            if (!value.trim())
+                return fail('empty_value', true, 'The translator returned no usable text');
+            const warnings = [];
+            // A plural added for a count placeholder is validated as ICU too.
+            if (entry.icu || (0, icu_message_1.isIcuMessage)(value)) {
+                const issues = (0, icu_message_1.compareIcuMessages)(entry.value, value, targetLocale, { pluralizable: entry.countArgs ?? [] });
+                const error = issues.find((i) => i.severity === 'error');
+                if (error)
+                    return fail('icu_invalid', true, error.message);
+                const lost = missingSpans(entry.value, value, neverTranslateTerms);
+                if (lost.length > 0)
+                    return fail('placeholder_lost', true, `Placeholder problem: dropped ${lost.join(', ')}`);
+                // Every branch must keep its own tags/URLs/terms, not just one of them.
+                const branch = (0, icu_spans_1.branchSpanProblems)(entry.value, value, neverTranslateTerms);
+                if (branch.length > 0) {
+                    const reason = branch.some((p) => p.lost.length) ? 'placeholder_lost' : 'markup_mismatch';
+                    return fail(reason, true, `Placeholder problem in ${branch.map(icu_spans_1.describeBranchSpanProblem).join('; ')} (each branch needs the source's tags and links)`);
+                }
+                warnings.push(...issues.map((i) => i.message));
+            }
+            if (isUnchangedSentence(entry.sendText, keyResult.value) || (0, untranslated_1.isUntranslatedInto)(entry.value, value, targetLocale)) {
+                return fail('untranslated', true, `Returned unchanged instead of translated into ${targetLocale}`);
+            }
+            const quality = (0, translation_quality_1.validateTranslationQuality)(entry.value, value);
+            // Tag counts legitimately change with an ICU message's branch count;
+            // its tags were already checked as a set above.
+            if (!entry.icu && !(0, icu_message_1.isIcuMessage)(value) && quality.issues?.some((i) => i.type === 'html_tag_mismatch')) {
+                return fail('markup_mismatch', true, 'HTML/JSX tags differ from the source');
+            }
+            if (quality.issues?.some((i) => i.type === 'suspicious_length')) {
+                warnings.push('Length differs a lot from the source; check it fits the UI');
+            }
+            return { ok: true, value, warnings };
+        };
+        const translateBatch = async (batch, hints) => {
+            const batchGlossary = [
+                ...glossaryForLocale.filter((g) => batch.some((b) => (0, glossary_1.sourceHasTerm)(b.value, g.term, neverTranslateTerms))),
+                // Untokenized ICU text: keep never-translate terms as-is via the glossary.
+                ...neverTranslateTerms
+                    .filter((t) => batch.some((b) => b.icu && (0, glossary_1.sourceHasTerm)(b.value, t)))
+                    .map((t) => ({ term: t, translation: t })),
+            ];
+            const keyResults = await translator.translateBatch({
+                entries: batch.map((b) => ({
+                    key: b.key,
+                    value: b.sendText,
+                    parentContext: contextMap?.[b.key],
+                    extractionContext: extractionContextMap?.[b.key],
+                })),
+                sourceLang,
+                targetLang,
+                brandVoice,
+                targetLocale,
+                glossary: batchGlossary.length > 0 ? batchGlossary : undefined,
+                hints,
+            });
+            const byKey = new Map(keyResults.map((r) => [r.key, r]));
+            for (const b of batch)
+                outcomes.set(b.key, judge(b, byKey.get(b.key)));
+        };
+        // A failed request fails only its own keys — except BYOK, where it means
+        // the customer's key/quota is the problem and the whole run should stop
+        // with that error rather than produce a partial result.
+        const runBatches = async (batches, hintsFor) => {
+            let byokError = null;
+            await (0, concurrent_map_1.concurrentMap)(batches, async (batch, i) => {
+                onProgress?.(`Translating batch ${i + 1}/${batches.length} for ${targetLang}...`);
+                const hints = hintsFor
+                    ? Object.fromEntries(batch.map((b) => [b.key, hintsFor(b)]).filter(([, h]) => !!h))
+                    : undefined;
+                try {
+                    await translateBatch(batch, hints);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    logger_1.engineLogger.error('Translation batch failed', { error: message, sourceLang, targetLang });
+                    if (byokConfig)
+                        byokError ?? (byokError = error instanceof Error ? error : new Error(message));
+                    for (const b of batch) {
+                        outcomes.set(b.key, { ok: false, reason: 'provider_error', retryable: true, message });
+                    }
+                }
+            }, TRANSLATE_CONCURRENCY);
+            if (byokError)
+                throw byokError;
+        };
+        /**
+         * Translate ICU entries with a plain-text translator, branch by branch:
+         * the branch sentences of all entries go out in as few requests as
+         * possible, then each entry is put back together and validated like any
+         * ICU translation. One outcome per entry.
+         */
+        const translateByBranches = async (entries, provider) => {
+            const out = new Map();
+            const plans = new Map();
+            const requests = [];
+            const unitKey = (key, id) => `${key}#branch${id}`;
+            for (const b of entries) {
+                const plan = (0, icu_branches_1.planIcuBranches)(b.value, targetLocale, {
+                    neverTranslateTerms,
+                    // Always a plain-text translator here: fixed terms go as tokens.
+                    fixedTerms: glossaryForLocale,
+                    valuePlaceholder: options.pluralValuePlaceholders?.[b.key],
+                    pluralizeArgs: b.countArgs,
+                });
+                if ('error' in plan) {
+                    out.set(b.key, { ok: false, reason: 'unsupported_by_provider', retryable: false, message: `This ICU message can't be translated branch by branch: ${plan.error}` });
+                    continue;
+                }
+                plans.set(b.key, { entry: b, plan });
+                for (const u of plan.units) {
+                    if (u.passthrough)
+                        continue;
+                    requests.push({ key: unitKey(b.key, u.id), value: u.sendText, parentContext: contextMap?.[b.key], extractionContext: extractionContextMap?.[b.key] });
+                }
+            }
+            const results = new Map();
+            const sendAll = async (list) => {
+                const batches = chunk(list, BRANCH_BATCH_SIZE);
+                await (0, concurrent_map_1.concurrentMap)(batches, async (batch, i) => {
+                    onProgress?.(`Translating plural/select branches ${i + 1}/${batches.length} for ${targetLang}...`);
+                    try {
+                        const keyResults = await provider.translateBatch({ entries: batch, sourceLang, targetLang, targetLocale });
+                        for (const r of keyResults)
+                            results.set(r.key, r);
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        logger_1.engineLogger.error('Branch translation batch failed', { error: message, sourceLang, targetLang });
+                        for (const e of batch)
+                            results.set(e.key, { key: e.key, status: 'failed', reason: 'provider_error', retryable: true, message });
+                    }
+                }, TRANSLATE_CONCURRENCY);
+            };
+            await sendAll(requests);
+            // Branches the translator skipped get one more request.
+            const skipped = requests.filter((r) => {
+                const res = results.get(r.key);
+                return !res || (res.status === 'failed' && res.reason === 'missing_from_response');
+            });
+            if (skipped.length > 0)
+                await sendAll(skipped);
+            const checkUnit = (unit, translated) => isUnchangedSentence(unit.sendText, translated) || (0, untranslated_1.isUntranslatedInto)(unit.sendText, translated, targetLocale)
+                ? { ok: false, reason: 'untranslated', retryable: true, message: `returned unchanged instead of translated into ${targetLocale}` }
+                : null;
+            for (const [key, { entry, plan }] of plans) {
+                const composed = plan.compose(new Map(plan.units.map((u) => [u.id, results.get(unitKey(key, u.id))])), checkUnit);
+                if (!composed.ok) {
+                    out.set(key, { ok: false, reason: composed.reason, retryable: composed.retryable, message: composed.message });
+                    continue;
+                }
+                // Each branch was cleaned up on its own; the message is checked as a whole.
+                out.set(key, judge(entry, { key, status: 'ok', value: composed.value }, false));
+            }
+            return out;
+        };
+        // With a plain-text translator, ICU entries (and counts that may become
+        // plurals) go branch by branch; everything else as before.
+        const viaBranches = new Set(isLlm ? [] : prepared.filter((b) => b.icu).map((b) => b.key));
+        const firstPassHint = (b) => (b.countArgs ? pluralHint(b.countArgs, targetLocale) : undefined);
+        await runBatches(chunk(prepared.filter((b) => !viaBranches.has(b.key)), BATCH_SIZE), isLlm ? firstPassHint : undefined);
+        if (viaBranches.size > 0) {
+            const branchEntries = prepared.filter((b) => viaBranches.has(b.key));
+            for (const [key, o] of await translateByBranches(branchEntries, translator))
+                outcomes.set(key, o);
+            // A count whose plural forms couldn't be built is translated as the
+            // plain message it is (as before target-side plurals), and says so.
+            const noPlural = branchEntries.filter((b) => b.plain && outcomes.get(b.key)?.ok === false);
+            if (noPlural.length > 0) {
+                const why = new Map(noPlural.map((b) => [b.key, outcomes.get(b.key).message]));
+                await runBatches(chunk(noPlural.map((b) => ({ ...b, ...b.plain, icu: false, countArgs: undefined, plain: undefined })), BATCH_SIZE));
+                for (const b of noPlural) {
+                    const o = outcomes.get(b.key);
+                    if (o?.ok)
+                        o.warnings.push(`Translated as plain text: ${targetLocale} plural forms couldn't be built (${why.get(b.key)})`);
+                }
+            }
+        }
+        // 3. One targeted repair attempt for keys that failed validation, telling
+        //    the model exactly what was wrong. NLLB is deterministic, so for it
+        //    only keys it skipped are worth asking for again.
+        const toRepair = prepared.filter((b) => {
+            const o = outcomes.get(b.key);
+            return o && !o.ok && o.retryable && o.reason !== 'provider_error' && !viaBranches.has(b.key) && (isLlm || o.reason === 'missing_from_response');
+        });
+        if (toRepair.length > 0) {
+            logger_1.engineLogger.info('Retrying keys that failed validation', { count: toRepair.length, targetLang });
+            onProgress?.(`Retrying ${toRepair.length} string(s) that failed checks for ${targetLang}...`);
+            const firstAttempt = new Map(toRepair.map((b) => [b.key, outcomes.get(b.key)]));
+            await runBatches(chunk(toRepair, REPAIR_BATCH_SIZE), isLlm
+                ? (b) => {
+                    const o = firstAttempt.get(b.key);
+                    if (!o || o.ok)
+                        return undefined;
+                    const fix = `A previous translation was rejected — ${o.message}. Fix that, and copy every [#VAR_n#] token exactly once.`;
+                    return b.countArgs ? `${fix} ${pluralHint(b.countArgs, targetLocale)}` : fix;
+                }
+                : undefined);
+        }
+        // 3b. Keys the LLM couldn't be reached for (rate limit, outage) get one
+        //     attempt on the fallback translator, if there is one. It's NLLB-class:
+        //     ICU messages go branch by branch, mixed-script strings stay failed.
+        const fellBack = new Set();
+        const fallback = providers.fallbackTranslator;
+        if (fallback && isLlm && nllbTarget) {
+            const toFallback = prepared.filter((b) => {
+                const o = outcomes.get(b.key);
+                // A count entry is a plain message: the fallback translates its tokenized form (no plural).
+                return o && !o.ok && o.reason === 'provider_error' && (!b.icu || !!b.plain) && !hasMixedScripts(b.value);
+            }).map((b) => (b.plain ? { ...b, ...b.plain, icu: false, countArgs: undefined, plain: undefined } : b));
+            if (toFallback.length > 0) {
+                logger_1.engineLogger.warn('LLM translator unavailable; trying the fallback translator', { count: toFallback.length, targetLang });
+                for (const batch of chunk(toFallback, BATCH_SIZE)) {
+                    try {
+                        const keyResults = await fallback.translateBatch({
+                            entries: batch.map((b) => ({ key: b.key, value: b.sendText, parentContext: contextMap?.[b.key] })),
+                            sourceLang,
+                            targetLang,
+                            targetLocale,
+                        });
+                        const byKey = new Map(keyResults.map((r) => [r.key, r]));
+                        for (const b of batch) {
+                            const o = judge(b, byKey.get(b.key), true);
+                            if (o.ok) {
+                                outcomes.set(b.key, o);
+                                fellBack.add(b.key);
+                            }
+                        }
+                    }
+                    catch (error) {
+                        logger_1.engineLogger.error('Fallback translation batch failed', { error: error instanceof Error ? error.message : String(error), targetLang });
+                    }
+                }
+            }
+            const icuToFallback = prepared.filter((b) => {
+                const o = outcomes.get(b.key);
+                return o && !o.ok && o.reason === 'provider_error' && b.icu && !b.plain && !hasMixedScripts(b.value);
+            });
+            if (icuToFallback.length > 0) {
+                logger_1.engineLogger.warn('LLM translator unavailable; trying the fallback translator branch by branch for ICU messages', { count: icuToFallback.length, targetLang });
+                for (const [key, o] of await translateByBranches(icuToFallback, fallback)) {
+                    if (o.ok) {
+                        outcomes.set(key, o);
+                        fellBack.add(key);
+                    }
+                }
+            }
+        }
+        // 4. Record results. Failed keys get no value at all: the locale file
+        //    omits them (the app shows the source string, honestly), the lockfile
+        //    doesn't mark them done, and the next run retries them.
+        const tmInserts = [];
+        for (const entry of prepared) {
+            const outcome = outcomes.get(entry.key);
+            if (!outcome || !outcome.ok) {
+                failures[entry.key] = outcome && !outcome.ok
+                    ? { reason: outcome.reason, retryable: outcome.retryable, message: outcome.message }
+                    : { reason: 'missing_from_response', retryable: true };
+                continue;
+            }
+            // No post-hoc glossary rewriting: a plain-text translator's output
+            // already has the fixed terms (restored from tokens, then validated);
+            // an LLM had them in the prompt, and if it ignored one that is a QA
+            // warning, never a blind replace that could hit a placeholder or URL.
+            const finalValue = outcome.value;
+            result[entry.key] = finalValue;
+            const qa = [...outcome.warnings, ...glossaryWarnings(entry.value, finalValue, glossaryForLocale, neverTranslateTerms)];
+            if (qa.length > 0)
+                metadata[entry.key] = { ...(metadata[entry.key] ?? {}), qa };
+            // Fallback output is a stopgap: keep it out of the shared cache and TM
+            // so they only ever hold the primary translator's work.
+            if (fellBack.has(entry.key)) {
+                const prev = metadata[entry.key] ?? {};
+                metadata[entry.key] = {
+                    ...prev,
+                    fallback: true,
+                    qa: [...(prev.qa ?? []), exports.FALLBACK_QA_WARNING],
+                };
+                continue;
+            }
+            if (options.progress)
+                options.progress.freshTranslations++;
+            // A translation shaped by an "always translate as" rule is this
+            // project's wording: the cache and TM are shared beyond the project,
+            // so it stays out of both (the lockfile keeps it for this project).
+            // Hits are checked against the glossary before reuse, so edits to the
+            // glossary re-translate anything stored that no longer complies.
+            if (projectWording(entry.value))
+                continue;
+            const cacheKey = (0, cache_keys_1.translationCacheKey)(sourceLang, storeLang, entry.hash);
+            if (cacheProvider) {
+                cacheProvider.set(cacheKey, outcome.value, cache_keys_1.TRANSLATION_CACHE_TTL_SECONDS).catch((err) => {
+                    logger_1.engineLogger.error('Failed to cache translation', { cacheKey, error: err });
+                });
+            }
+            if (projectId && !contextMap?.[entry.key] && !approvedSourceTexts.has(entry.value)) {
+                tmInserts.push({ key: entry.key, sourceText: entry.value, translatedText: outcome.value });
+            }
+        }
+        if (tmInserts.length > 0 && projectId && tmContext && !dryRun) {
+            // Normally the translator only sees strings TM had no entry for, so
+            // overwriting is safe; a forced re-translate overwrites on purpose.
+            // If the lookup failed, existing entries may be human edits — keep them.
+            const saved = await persistToTM(memory, tmInserts, projectId, tmContext, sourceLang, storeLang, { overwrite: !tmLookupFailed });
+            if (saved)
+                markInTm(tmInserts.map((i) => i.key));
+        }
+    }
+    const failureCount = Object.keys(failures).length;
+    if (failureCount > 0) {
+        logger_1.engineLogger.warn('Some strings could not be translated', { targetLang, failed: failureCount, of: keys.length });
+    }
+    // Every key this run produced gets metadata (possibly empty) so the lockfile
+    // replaces the previous run's — cache hits, fallbacks and mixed-script keys
+    // included — instead of keeping a stale fromMemory/fuzzyMatches.
+    for (const key of Object.keys(result)) {
+        const meta = { ...(metadata[key] ?? {}) };
+        // The glossary rules this translation was made (or checked) under: the
+        // lockfile re-translates the key when they change. Not recorded when the
+        // rules failed to load, so the next run that has them redoes the key.
+        if (rulesComplete) {
+            const fingerprint = (0, glossary_1.glossaryFingerprint)(entries[key], targetLocale, glossary);
+            if (fingerprint)
+                meta.glossaryHash = fingerprint;
+        }
+        const notes = (0, glossary_1.conflictNotes)(entries[key], glossary);
+        if (notes.length > 0)
+            meta.qa = [...(meta.qa ?? []), ...notes];
+        metadata[key] = meta;
+    }
+    return { result, stats: { tmHits }, metadata, failures };
+}
+/**
+ * Persist translations to the project owner's TM. Never throws: a TM failure
+ * must not fail the run, but it is logged at error level rather than skipped.
+ * `sourceLang`/`targetLang` are FLORES codes, matching what TM lookups use.
+ */
+async function persistToTM(memory, inserts, projectId, tmContext, sourceLang, targetLang, options = {}) {
+    if (!tmContext.ownerId) {
+        logger_1.engineLogger.error('TM persistence skipped: project has no resolvable owner', {
+            projectId,
+            count: inserts.length,
+        });
+        return false;
+    }
+    try {
+        await memory.saveBatch(tmContext.ownerId, projectId, inserts.map((insert) => ({
+            sourceText: insert.sourceText,
+            sourceLocale: sourceLang,
+            targetLocale: targetLang,
+            translatedText: insert.translatedText,
+            isoKey: insert.key,
+            projectName: tmContext.projectName ?? undefined,
+        })), options);
+        logger_1.engineLogger.info('TM persistence complete', { count: inserts.length, projectId, overwrite: options.overwrite ?? true });
+        return true;
+    }
+    catch (err) {
+        logger_1.engineLogger.error('TM persistence failed', {
+            count: inserts.length,
+            projectId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return false;
+    }
+}
+/**
+ * Backfill TM from translations that were reused without calling the
+ * translator (lockfile hits). Existing TM rows are left untouched.
+ * Locales are ISO codes here; identity translations (source === target) are
+ * skipped since they mean a previous run had no working translator.
+ */
+async function backfillTranslationMemory(projectId, sourceLocale, flatSource, translationsByLocale, excludeKeys = new Set(), providers = {}) {
+    const memory = providers.memory;
+    if (!memory)
+        return {};
+    const tmContext = await memory.getProjectContext(projectId);
+    const sourceLang = (0, language_codes_1.toFlores)(sourceLocale);
+    // Lockfile values are final output: project glossary substitutions and
+    // brand-voice rewording are baked in and can't be separated out. Shared TM
+    // must not carry them into the owner's other projects, so skip those.
+    const rules = await loadProjectTranslationRules(projectId, providers.rules);
+    if (rules.brandVoice) {
+        logger_1.engineLogger.info('Skipping lockfile TM backfill: project has a brand voice', { projectId });
+        return {};
+    }
+    if (!rules.complete) {
+        // Can't tell whether glossary/brand-voice wording is baked into these
+        // values; retry on a later run rather than risk leaking it into shared TM.
+        logger_1.engineLogger.warn('Skipping lockfile TM backfill: project rules failed to load', { projectId });
+        return {};
+    }
+    // Keys whose TM state is settled for a locale: written, or deliberately
+    // skipped. The caller records these so later runs don't redo them.
+    const settled = {};
+    for (const [locale, translations] of Object.entries(translationsByLocale)) {
+        if (locale === sourceLocale || !(0, language_codes_1.isSupported)(locale))
+            continue;
+        const inserts = [];
+        const skipped = [];
+        for (const [key, translatedText] of Object.entries(translations)) {
+            const sourceText = flatSource[key];
+            if (excludeKeys.has(key) ||
+                (0, glossary_1.hasFixedTerm)(sourceText ?? '', rules.glossary, locale) ||
+                !sourceText || !translatedText || sourceText === translatedText) {
+                skipped.push(key);
+                continue;
+            }
+            inserts.push({ key, sourceText, translatedText });
+        }
+        const saved = inserts.length === 0 ||
+            await persistToTM(memory, inserts, projectId, tmContext, sourceLang, (0, language_codes_1.storageLangCode)(locale), { overwrite: false });
+        if (saved)
+            settled[locale] = [...skipped, ...inserts.map((i) => i.key)];
+    }
+    return settled;
+}