@babelize/engine 0.1.0 → 0.1.3

package/dist/modules/translator/translate.js

@@ -1,43 +1,11 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FALLBACK_QA_WARNING = void 0;
+exports.loadProjectTranslationRules = loadProjectTranslationRules;
 exports.translateLocales = translateLocales;
 exports.backfillTranslationMemory = backfillTranslationMemory;
-const path = __importStar(require("path"));
 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");
@@ -47,21 +15,37 @@ 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
-/** 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);
+/**
+ * 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. A stored ICU translation stored before a check it now
+ * fails (e.g. Czech without its `few` branch) is translated again.
+ */
+function reusableTranslation(source, translated, targetPlurals, targetLocale) {
+    if (!targetPlurals && !(0, icu_message_1.isIcuMessage)(source) && (0, icu_message_1.isIcuMessage)(translated))
+        return false;
+    if (!(0, icu_message_1.isIcuMessage)(translated))
+        return true;
+    const pluralizable = (0, icu_message_1.isIcuMessage)(source) ? [] : (0, icu_message_1.countArguments)(source);
+    return !(0, icu_message_1.compareIcuMessages)(source, translated, targetLocale, { pluralizable }).some((i) => i.severity === 'error');
 }
 /** Per-entry instruction: pluralize a count argument if the target language needs it. */
 function pluralHint(args, targetLocale) {
@@ -85,12 +69,6 @@ function isUnchangedSentence(sentText, returnedText) {
     const words = norm(sentText).split(' ').filter((w) => /\p{L}{2,}/u.test(w));
     return words.length >= 3 && norm(sentText) === norm(returnedText);
 }
-function escapeTerm(term) {
-    return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function containsTerm(text, term) {
-    return new RegExp(`(?<![\\w])${escapeTerm(term)}(?![\\w])`, 'i').test(text);
-}
 /** 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()));
@@ -98,11 +76,24 @@ function missingSpans(source, translated, neverTranslateTerms) {
     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) {
+function glossaryWarnings(source, translated, glossary, neverTranslateTerms) {
     return glossary
-        .filter((g) => containsTerm(source, g.term) && !(0, glossary_match_1.containsGlossaryTranslation)(translated, g.translation))
+        .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
@@ -156,29 +147,22 @@ function hasMixedScripts(text) {
  * project-specific wording may be baked in.
  */
 async function loadProjectTranslationRules(projectId, rules) {
-    let neverTranslateTerms = [];
-    let alwaysTranslateAsEntries = [];
+    let glossary = glossary_1.EMPTY_GLOSSARY;
     let brandVoice = null;
     let complete = true;
     if (!rules)
-        return { neverTranslateTerms, alwaysTranslateAsEntries, brandVoice, complete };
+        return { glossary, brandVoice, complete };
     try {
         const entries = await rules.getGlossary(projectId);
         if (entries?.length) {
-            neverTranslateTerms = entries
-                .filter((e) => e.type === 'never_translate')
-                .map((e) => e.term);
-            alwaysTranslateAsEntries = entries
-                .filter((e) => e.type === 'always_translate_as')
-                .map((e) => ({
-                term: e.term,
-                type: 'always_translate_as',
-                translations: e.translations || {},
-            }));
+            glossary = (0, glossary_1.normalizeGlossary)(entries);
             logger_1.engineLogger.info('Loaded project glossary', {
-                neverTranslate: neverTranslateTerms.length,
-                alwaysTranslateAs: alwaysTranslateAsEntries.length,
+                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) {
@@ -198,16 +182,32 @@ async function loadProjectTranslationRules(projectId, rules) {
         complete = false;
         logger_1.engineLogger.warn('Failed to load brand voice', { error: err });
     }
-    return { neverTranslateTerms, alwaysTranslateAsEntries, brandVoice, complete };
+    return { glossary, brandVoice, complete };
 }
 /**
- * Whether a source string is subject to one of the project's "always
- * translate as" rules for this locale, i.e. its stored translation has
- * project-specific wording baked in.
+ * 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.
  */
-function hasAlwaysTranslateAsTerm(sourceText, entries, targetLocale) {
-    return entries.some((e) => !!e.translations[targetLocale] &&
-        new RegExp(`\\b${e.term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i').test(sourceText));
+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 = [];
@@ -231,50 +231,16 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
             delete flatSource[key];
         }
     }
-    // Fetch glossary entries for this project
-    let neverTranslateTerms = [];
-    let alwaysTranslateAsEntries = [];
-    let brandVoice = null;
-    let rulesComplete = true;
-    if (projectId) {
-        const rules = await loadProjectTranslationRules(projectId, providers.rules);
-        neverTranslateTerms = rules.neverTranslateTerms;
-        alwaysTranslateAsEntries = rules.alwaysTranslateAsEntries;
-        brandVoice = rules.brandVoice;
-        rulesComplete = rules.complete;
-    }
-    // Fall back to workspace config for CLI/MCP runs (no projectId)
-    if (!projectId) {
-        try {
-            const babelizeConfigPath = path.join(workspace.path, '.babelize', 'config.json');
-            const fileUtils = await Promise.resolve().then(() => __importStar(require('../../utils/file-utils')));
-            const { readJsonFile } = fileUtils;
-            if (await fileUtils.pathExists(babelizeConfigPath)) {
-                const config = await readJsonFile(babelizeConfigPath);
-                if (config?.customTranslations) {
-                    for (const [term, entry] of Object.entries(config.customTranslations)) {
-                        if (entry.neverTranslate) {
-                            neverTranslateTerms.push(term);
-                        }
-                        if (entry.translations) {
-                            alwaysTranslateAsEntries.push({
-                                term,
-                                type: 'always_translate_as',
-                                translations: entry.translations,
-                            });
-                        }
-                    }
-                    logger_1.engineLogger.info('Loaded glossary from workspace config', {
-                        neverTranslate: neverTranslateTerms.length,
-                        alwaysTranslateAs: alwaysTranslateAsEntries.length,
-                    });
-                }
-            }
-        }
-        catch (err) {
-            logger_1.engineLogger.warn('Failed to load glossary from workspace config', { error: err });
-        }
-    }
+    // 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.');
@@ -308,8 +274,8 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
         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) && brandVoice);
-        const translationResult = await translateEntries(entriesToTranslate, sourceLangCode, targetLangCode, projectId, onProgress, neverTranslateTerms, alwaysTranslateAsEntries, targetLocale, cacheProvider, byokConfig, contextMap, extractionContextMap, hasBrandVoiceInPrompt ? (brandVoice || undefined) : undefined, dryRun, forceTranslation, providers, rulesComplete, options);
+        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;
@@ -325,6 +291,7 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
         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.
@@ -348,7 +315,10 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
                         // 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);
-                        const safe = (0, placeholder_protection_1.sameProtectedSpans)(before, v, neverTranslateTerms) &&
+                        // ...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;
@@ -368,7 +338,9 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
             ...translatedData,
             _meta: { ...existingTranslatedMeta, dir: (0, language_codes_1.isRTL)(targetLocale) ? 'rtl' : 'ltr', language: targetLocale },
         };
-        if (!dryRun)
+        // 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,
@@ -418,7 +390,7 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
         metadata: perLocaleMetadata
     };
 }
-async function translateEntries(entries, sourceLang, targetLang, projectId, onProgress, neverTranslateTerms = [], alwaysTranslateAsEntries = [], targetLocale = '', cacheProvider, byokConfig, contextMap, extractionContextMap, brandVoice, dryRun = false, forceTranslation = false, providers = {}, rulesComplete = true, options = {}) {
+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);
@@ -433,6 +405,14 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
         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];
@@ -440,8 +420,16 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
         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 };
-        if (cached.hit && cached.data !== null && reusableTranslation(text, cached.data, !!options.targetPlurals)) {
-            result[key] = applyGlossaryPostProcessing(text, cached.data, neverTranslateTerms, alwaysTranslateAsEntries, targetLocale);
+        // 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, targetLocale) && !(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 };
@@ -449,8 +437,8 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
             // 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 && !hasAlwaysTranslateAsTerm(text, alwaysTranslateAsEntries, targetLocale)) {
-                cacheBackfill.push({ key, sourceText: text, translatedText: restoreNeverTranslate(text, cached.data, neverTranslateTerms) });
+            if (rulesComplete && !entryContext && !brandVoice && !projectWording(text)) {
+                cacheBackfill.push({ key, sourceText: text, translatedText: cached.data });
             }
         }
         else {
@@ -514,13 +502,17 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
                     continue;
                 }
                 const lookup = (0, memory_matcher_1.matchFromMemory)(allMemory, entry.value, storeLang);
-                if (lookup.hit && lookup.translatedText && reusableTranslation(entry.value, lookup.translatedText, !!options.targetPlurals)) {
-                    result[entry.key] = applyGlossaryPostProcessing(entry.value, lookup.translatedText, neverTranslateTerms, alwaysTranslateAsEntries, targetLocale);
+                // 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, targetLocale) && !(0, untranslated_1.isUntranslatedInto)(entry.value, lookup.translatedText, targetLocale)) {
+                    result[entry.key] = lookup.translatedText;
                     tmHits++;
                     metadata[entry.key] = { fromMemory: true, inTm: true };
-                    // Warm Redis cache (stored pre-glossary, like every other cache write)
+                    // Warm the cache (never with this project's glossary wording)
                     const cacheKey = (0, cache_keys_1.translationCacheKey)(sourceLang, storeLang, entry.hash);
-                    if (cacheProvider) {
+                    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 });
                         });
@@ -553,30 +545,29 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
         });
     }
     const failures = {};
-    // LLM providers get structure-aware prompts and repair attempts; the NLLB
-    // service can't handle ICU or mixed-script text, so those fail up front.
-    const isLlm = !!byokConfig || !!providers.translator;
+    // 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) {
-        const glossaryForLocale = alwaysTranslateAsEntries
-            .filter((e) => e.translations[targetLocale])
-            .map((e) => ({ term: e.term, translation: e.translations[targetLocale] }));
         // 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.
+        //    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 && (icu || hasMixedScripts(entry.value) || !nllbTarget)) {
+            if (!isLlm && (hasMixedScripts(entry.value) || !nllbTarget)) {
                 failures[entry.key] = {
                     reason: 'unsupported_by_provider',
                     retryable: false,
                     message: !nllbTarget
                         ? `${targetLocale} needs an LLM translation provider`
-                        : icu
-                            ? 'ICU plural/select messages need an LLM translation provider'
-                            : 'Text mixing writing systems needs an LLM translation provider',
+                        : 'Text mixing writing systems needs an LLM translation provider',
                 };
                 continue;
             }
@@ -584,24 +575,44 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
             // 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.
-            const countArgs = isLlm && options.targetPlurals && !icu ? (0, icu_message_1.countArguments)(entry.value) : [];
-            const tokenized = (0, placeholder_protection_1.protectText)(entry.value, neverTranslateTerms);
-            const sendRaw = icu || countArgs.length > 0;
-            const prot = sendRaw ? { text: entry.value, tokens: [] } : tokenized;
-            if ((0, placeholder_protection_1.hasNothingToTranslate)(tokenized.text)) {
+            // 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 ? { sendText: tokenized.text, tokens: tokenized.tokens } : undefined,
+                plain: countArgs.length || (isLlm && !icu)
+                    ? { sendText: withFixed.text, tokens: withFixed.tokens, restore: withFixed.restore }
+                    : undefined,
             });
         }
         // 2. Translate in batches; judge every key independently.
@@ -623,7 +634,11 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
             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 }), 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)) {
@@ -642,7 +657,7 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
                 }
                 warnings.push(...issues.map((i) => i.message));
             }
-            if (isUnchangedSentence(entry.sendText, keyResult.value)) {
+            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);
@@ -658,10 +673,10 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
         };
         const translateBatch = async (batch, hints) => {
             const batchGlossary = [
-                ...glossaryForLocale.filter((g) => batch.some((b) => containsTerm(b.value, g.term))),
+                ...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 && containsTerm(b.value, t)))
+                    .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({
@@ -708,14 +723,104 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
             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, BATCH_SIZE), isLlm ? firstPassHint : 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' && (isLlm || o.reason === 'missing_from_response');
+            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 });
@@ -732,8 +837,8 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
                 : 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,
-        //     so ICU and mixed-script strings stay failed.
+        //     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) {
@@ -766,6 +871,19 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
                     }
                 }
             }
+            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
@@ -779,9 +897,13 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
                     : { reason: 'missing_from_response', retryable: true };
                 continue;
             }
-            const finalValue = applyGlossaryPostProcessing(entry.value, outcome.value, [], alwaysTranslateAsEntries, targetLocale);
+            // 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)];
+            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
@@ -795,10 +917,15 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
                 };
                 continue;
             }
-            // Cache and TM store the translation *before* project glossary rules
-            // ("always translate as") are applied; those rules are re-applied on
-            // every hit, so glossary edits reach cached strings and one project's
-            // glossary never leaks into the owner's other projects through TM.
+            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) => {
@@ -826,25 +953,22 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
     // 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)) {
-        if (!metadata[key])
-            metadata[key] = {};
+        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 };
 }
-/** Put back never-translate terms that were masked before translation. */
-function restoreNeverTranslate(originalText, translatedText, neverTranslateTerms) {
-    if (neverTranslateTerms.length === 0)
-        return translatedText;
-    const { terms: usedTerms } = (0, glossary_1.applyGlossaryMask)(originalText, neverTranslateTerms);
-    return (0, glossary_1.restoreGlossaryMask)(translatedText, usedTerms);
-}
-function applyGlossaryPostProcessing(originalText, translatedText, neverTranslateTerms, alwaysTranslateAsEntries, targetLocale) {
-    let processed = restoreNeverTranslate(originalText, translatedText, neverTranslateTerms);
-    if (alwaysTranslateAsEntries.length > 0 && targetLocale) {
-        processed = (0, glossary_1.applyAlwaysTranslateAs)(processed, alwaysTranslateAsEntries, targetLocale);
-    }
-    return processed;
-}
 /**
  * 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.
@@ -916,7 +1040,7 @@ async function backfillTranslationMemory(projectId, sourceLocale, flatSource, tr
         for (const [key, translatedText] of Object.entries(translations)) {
             const sourceText = flatSource[key];
             if (excludeKeys.has(key) ||
-                hasAlwaysTranslateAsTerm(sourceText ?? '', rules.alwaysTranslateAsEntries, locale) ||
+                (0, glossary_1.hasFixedTerm)(sourceText ?? '', rules.glossary, locale) ||
                 !sourceText || !translatedText || sourceText === translatedText) {
                 skipped.push(key);
                 continue;