@babelize/engine 0.2.1 → 0.3.1

package/dist/modules/lockfile/schema.d.ts

@@ -25,6 +25,8 @@ export declare const lockfileEntrySchema: z.ZodObject<{
          * catalogue), not from Babelize: glossary edits don't overwrite it.
          */
         external: z.ZodOptional<z.ZodBoolean>;
+        /** Edited in the dashboard (a translation override), not translated by Babelize. */
+        manual: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         sourceHash?: string | undefined;
         fromMemory?: boolean | undefined;
@@ -32,6 +34,7 @@ export declare const lockfileEntrySchema: z.ZodObject<{
         pseudo?: boolean | undefined;
         glossaryHash?: string | undefined;
         external?: boolean | undefined;
+        manual?: boolean | undefined;
     }, {
         sourceHash?: string | undefined;
         fromMemory?: boolean | undefined;
@@ -39,6 +42,7 @@ export declare const lockfileEntrySchema: z.ZodObject<{
         pseudo?: boolean | undefined;
         glossaryHash?: string | undefined;
         external?: boolean | undefined;
+        manual?: boolean | undefined;
     }>>>;
 }, "strip", z.ZodTypeAny, {
     sourceHash: string;
@@ -51,6 +55,7 @@ export declare const lockfileEntrySchema: z.ZodObject<{
         pseudo?: boolean | undefined;
         glossaryHash?: string | undefined;
         external?: boolean | undefined;
+        manual?: boolean | undefined;
     }> | undefined;
 }, {
     sourceHash: string;
@@ -63,6 +68,7 @@ export declare const lockfileEntrySchema: z.ZodObject<{
         pseudo?: boolean | undefined;
         glossaryHash?: string | undefined;
         external?: boolean | undefined;
+        manual?: boolean | undefined;
     }> | undefined;
 }>;
 export type LockfileEntry = z.infer<typeof lockfileEntrySchema>;
@@ -96,6 +102,8 @@ export declare const lockfileDataSchema: z.ZodObject<{
              * catalogue), not from Babelize: glossary edits don't overwrite it.
              */
             external: z.ZodOptional<z.ZodBoolean>;
+            /** Edited in the dashboard (a translation override), not translated by Babelize. */
+            manual: z.ZodOptional<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             sourceHash?: string | undefined;
             fromMemory?: boolean | undefined;
@@ -103,6 +111,7 @@ export declare const lockfileDataSchema: z.ZodObject<{
             pseudo?: boolean | undefined;
             glossaryHash?: string | undefined;
             external?: boolean | undefined;
+            manual?: boolean | undefined;
         }, {
             sourceHash?: string | undefined;
             fromMemory?: boolean | undefined;
@@ -110,6 +119,7 @@ export declare const lockfileDataSchema: z.ZodObject<{
             pseudo?: boolean | undefined;
             glossaryHash?: string | undefined;
             external?: boolean | undefined;
+            manual?: boolean | undefined;
         }>>>;
     }, "strip", z.ZodTypeAny, {
         sourceHash: string;
@@ -122,6 +132,7 @@ export declare const lockfileDataSchema: z.ZodObject<{
             pseudo?: boolean | undefined;
             glossaryHash?: string | undefined;
             external?: boolean | undefined;
+            manual?: boolean | undefined;
         }> | undefined;
     }, {
         sourceHash: string;
@@ -134,6 +145,7 @@ export declare const lockfileDataSchema: z.ZodObject<{
             pseudo?: boolean | undefined;
             glossaryHash?: string | undefined;
             external?: boolean | undefined;
+            manual?: boolean | undefined;
         }> | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
@@ -148,6 +160,7 @@ export declare const lockfileDataSchema: z.ZodObject<{
             pseudo?: boolean | undefined;
             glossaryHash?: string | undefined;
             external?: boolean | undefined;
+            manual?: boolean | undefined;
         }> | undefined;
     }>;
     projectId: string;
@@ -165,6 +178,7 @@ export declare const lockfileDataSchema: z.ZodObject<{
             pseudo?: boolean | undefined;
             glossaryHash?: string | undefined;
             external?: boolean | undefined;
+            manual?: boolean | undefined;
         }> | undefined;
     }>;
     projectId: string;

package/dist/modules/lockfile/schema.js

@@ -32,6 +32,8 @@ exports.lockfileEntrySchema = zod_1.z.object({
          * catalogue), not from Babelize: glossary edits don't overwrite it.
          */
         external: zod_1.z.boolean().optional(),
+        /** Edited in the dashboard (a translation override), not translated by Babelize. */
+        manual: zod_1.z.boolean().optional(),
     })).optional(),
 });
 // ─────────────────────────────────────────────────────────────

package/dist/modules/overrides/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Translation overrides: translations a person edited in the dashboard.
+ *
+ * They win over the lockfile, translation memory and the translator, on every
+ * run, for as long as the source text is the one that was edited. When the
+ * source text changes the edit no longer fits: it is not applied, the key is
+ * translated as usual, and the run reports it as replaced.
+ */
+import type { LocaleData } from '../../runtime/types';
+export interface TranslationOverride {
+    key: string;
+    locale: string;
+    text: string;
+    /** The source text the edit was made against. */
+    sourceText: string;
+}
+export interface OverrideReport {
+    /** Edits written into this run's locale files. */
+    applied: Array<{
+        key: string;
+        locale: string;
+    }>;
+    /** Edits whose source text has changed since: not applied, translated as usual. */
+    replaced: Array<{
+        key: string;
+        locale: string;
+        text: string;
+        sourceText: string;
+    }>;
+}
+/** Set `key` in locale data: a literal flat key when the file has one, else a nested path. */
+export declare function setLocaleValue(data: LocaleData, key: string, value: string): void;
+/**
+ * Apply edits to the run's locale data in place. `source` is the flat source
+ * locale (key → text). Edits for a key the run no longer has, or a locale it
+ * doesn't write, are left alone (kept for when they come back).
+ */
+export declare function applyTranslationOverrides(locales: Array<{
+    locale: string;
+    data: LocaleData;
+}>, source: Record<string, string>, overrides: TranslationOverride[]): OverrideReport;

package/dist/modules/overrides/index.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Translation overrides: translations a person edited in the dashboard.
+ *
+ * They win over the lockfile, translation memory and the translator, on every
+ * run, for as long as the source text is the one that was edited. When the
+ * source text changes the edit no longer fits: it is not applied, the key is
+ * translated as usual, and the run reports it as replaced.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLocaleValue = setLocaleValue;
+exports.applyTranslationOverrides = applyTranslationOverrides;
+/** Set `key` in locale data: a literal flat key when the file has one, else a nested path. */
+function setLocaleValue(data, key, value) {
+    if (typeof data[key] === 'string' || !key.includes('.')) {
+        data[key] = value;
+        return;
+    }
+    const parts = key.split('.');
+    let current = data;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (typeof current[part] !== 'object' || current[part] === null)
+            current[part] = {};
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+/**
+ * Apply edits to the run's locale data in place. `source` is the flat source
+ * locale (key → text). Edits for a key the run no longer has, or a locale it
+ * doesn't write, are left alone (kept for when they come back).
+ */
+function applyTranslationOverrides(locales, source, overrides) {
+    const report = { applied: [], replaced: [] };
+    const byLocale = new Map(locales.map((l) => [l.locale, l]));
+    for (const o of overrides) {
+        const target = byLocale.get(o.locale);
+        const current = source[o.key];
+        if (!target || current === undefined)
+            continue;
+        if (current !== o.sourceText) {
+            report.replaced.push({ key: o.key, locale: o.locale, text: o.text, sourceText: o.sourceText });
+            continue;
+        }
+        setLocaleValue(target.data, o.key, o.text);
+        report.applied.push({ key: o.key, locale: o.locale });
+    }
+    return report;
+}

package/dist/modules/translator/budget.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A run's translation budget: the most (key, locale) pairs it may send to the
+ * translator (the caller's credit budget, see EngineConfigV2.maxTranslations).
+ *
+ * Locales are translated concurrently, so the budget is granted in slot order
+ * (the locale's position in the run) rather than first come, first served:
+ * each locale claims what it needs once its cache and translation-memory
+ * lookups are done, and a claim is only settled after every earlier slot has
+ * claimed. The same project and budget therefore always translate the same
+ * pairs: earlier languages are completed first, keys in source order.
+ *
+ * Every slot must claim exactly once (0 when it has nothing to send), or the
+ * slots after it wait forever.
+ */
+export declare class TranslationBudget {
+    private remaining;
+    private nextSlot;
+    private readonly pending;
+    constructor(limit: number);
+    /** Resolves with how many of `wanted` pairs slot `slot` may translate. */
+    claim(slot: number, wanted: number): Promise<number>;
+    private settle;
+}
+/** A `maxTranslations` value that caps the run: a finite number >= 0. */
+export declare function isTranslationCap(max: number | undefined): max is number;

package/dist/modules/translator/budget.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranslationBudget = void 0;
+exports.isTranslationCap = isTranslationCap;
+/**
+ * A run's translation budget: the most (key, locale) pairs it may send to the
+ * translator (the caller's credit budget, see EngineConfigV2.maxTranslations).
+ *
+ * Locales are translated concurrently, so the budget is granted in slot order
+ * (the locale's position in the run) rather than first come, first served:
+ * each locale claims what it needs once its cache and translation-memory
+ * lookups are done, and a claim is only settled after every earlier slot has
+ * claimed. The same project and budget therefore always translate the same
+ * pairs: earlier languages are completed first, keys in source order.
+ *
+ * Every slot must claim exactly once (0 when it has nothing to send), or the
+ * slots after it wait forever.
+ */
+class TranslationBudget {
+    constructor(limit) {
+        this.nextSlot = 0;
+        this.pending = new Map();
+        this.remaining = Math.max(0, Math.floor(limit));
+    }
+    /** Resolves with how many of `wanted` pairs slot `slot` may translate. */
+    claim(slot, wanted) {
+        return new Promise((resolve) => {
+            this.pending.set(slot, { wanted: Math.max(0, Math.floor(wanted)), resolve });
+            this.settle();
+        });
+    }
+    settle() {
+        for (let next = this.pending.get(this.nextSlot); next; next = this.pending.get(this.nextSlot)) {
+            this.pending.delete(this.nextSlot);
+            this.nextSlot++;
+            const granted = Math.min(next.wanted, this.remaining);
+            this.remaining -= granted;
+            next.resolve(granted);
+        }
+    }
+}
+exports.TranslationBudget = TranslationBudget;
+/** A `maxTranslations` value that caps the run: a finite number >= 0. */
+function isTranslationCap(max) {
+    return typeof max === 'number' && Number.isFinite(max) && max >= 0;
+}

package/dist/modules/translator/icu-branches.d.ts

@@ -49,6 +49,13 @@ interface NumberSlot {
      * instead of showing it, and the branch is still exact.
      */
     mayBeSpelledOut: boolean;
+    /**
+     * Words for "one" in the target language, when this slot is the number 1 in
+     * a branch that also covers other numbers (French "one" is 0 and 1). The
+     * translator often writes "Vous avez un article" for "You have 1 item"; the
+     * word is put back as the count, which keeps the branch right for 0 too.
+     */
+    oneWords?: string[];
 }
 export interface BranchUnit {
     /** Unique within the plan. */

package/dist/modules/translator/icu-branches.js

@@ -54,6 +54,21 @@ const CANDIDATES = (() => {
 const ARG_SENTINEL = /\uE001(\d+)\uE001/g;
 const POUND_SENTINEL = '\uE002';
 const TOKEN_PATTERN = /\[\s*#\s*VAR_\d+\s*#\s*\]/gi;
+/** Spelled-out "one" (as an article or numeral) in languages whose "one" category has several numbers. */
+const ONE_WORDS = {
+    fr: ['un', 'une'],
+    es: ['un', 'una', 'uno'],
+    pt: ['um', 'uma'],
+    it: ['un', 'uno', 'una'],
+    ca: ['un', 'una'],
+    ro: ['un', 'o'],
+    hi: ['एक'],
+    bn: ['এক', 'একটি'],
+    gu: ['એક'],
+    mr: ['एक'],
+    fa: ['یک'],
+    hy: ['մեկ'],
+};
 class PlanError extends Error {
 }
 /** Plural categories of a locale, CLDR order. */
@@ -218,7 +233,8 @@ function makeUnit(nodes, path, state) {
             used.add(pick);
             // A plural added over a plain count must show it in every branch (compareIcuMessages), so no spelling out there.
             const mayBeSpelledOut = numbers.length === 1 && !(state.options.pluralizeArgs ?? []).includes(occ.owner.name);
-            slot = { text: pick, count: 0, restore: occ.restore, label: occ.label, mayBeSpelledOut };
+            const oneWords = pick === '1' && !mayBeSpelledOut ? ONE_WORDS[state.targetLocale.split(/[-_]/)[0].toLowerCase()] : undefined;
+            slot = { text: pick, count: 0, restore: occ.restore, label: occ.label, mayBeSpelledOut, ...(oneWords ? { oneWords } : {}) };
             slotsByKind.set(kindKey, slot);
         }
         slot.count++;
@@ -287,10 +303,20 @@ function restoreNumbers(translated, slots) {
             return slot.restore;
         });
     }).join('');
+    let text = out;
     for (const slot of slots) {
-        const n = found.get(slot) ?? 0;
+        let n = found.get(slot) ?? 0;
         if (n === 0 && slot.mayBeSpelledOut)
             continue;
+        if (n === 0 && slot.count === 1 && slot.oneWords) {
+            // "Vous avez un article" → "Vous avez # article", when the word is there exactly once.
+            const word = new RegExp(`(?<![\\p{L}\\p{M}])(?:${slot.oneWords.join('|')})(?![\\p{L}\\p{M}])`, 'giu');
+            const hits = text.match(word) ?? [];
+            if (hits.length === 1) {
+                text = text.replace(word, slot.restore);
+                n = 1;
+            }
+        }
         if (n !== slot.count) {
             return {
                 problem: n === 0
@@ -299,7 +325,7 @@ function restoreNumbers(translated, slots) {
             };
         }
     }
-    return { text: out };
+    return { text };
 }
 /** ICU-escape literal text: apostrophes before syntax, and `{`, `}` (and `#` in a plural) quoted. */
 function escapeIcuText(text, inPlural) {

package/dist/modules/translator/translate.d.ts

@@ -32,6 +32,13 @@ export interface TranslateOptions {
     progress?: {
         freshTranslations: number;
     };
+    /**
+     * Most (key, locale) pairs to send to the translator this call (the run's
+     * credit budget). Cache, TM and passthrough reuse don't count. Locales are
+     * filled in `targetLocales` order, keys in source order; the rest are
+     * returned as `skippedForBudget`. Undefined or negative: no cap.
+     */
+    maxTranslations?: number;
 }
 export interface LoadedTranslationRules {
     glossary: GlossaryRules;
@@ -59,6 +66,10 @@ export declare function translateLocales(workspace: WorkspaceInfo, sourceLocale:
             error: string;
         }[];
         failures: TranslationFailure[];
+        skippedForBudget: {
+            key: string;
+            locale: string;
+        }[];
     };
     stats: {
         tmHits: number;

package/dist/modules/translator/translate.js

@@ -24,6 +24,7 @@ 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 budget_1 = require("./budget");
 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';
@@ -214,6 +215,7 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
     const locales = [];
     const errors = [];
     const failures = [];
+    const skippedForBudget = [];
     let tmHitsTotal = 0;
     const perLocaleMetadata = {};
     // Ensure locale output directories exist for all target locales
@@ -248,7 +250,23 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
     }
     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) => {
+    // The run's translation budget, granted in locale order (see TranslationBudget).
+    const budget = (0, budget_1.isTranslationCap)(options.maxTranslations) ? new budget_1.TranslationBudget(options.maxTranslations) : null;
+    // Every locale claims its share of the budget exactly once, even when it has
+    // nothing to send or fails, or the locales after it never get theirs.
+    const withBudget = (fn) => async (targetLocale, slot) => {
+        if (!budget)
+            return fn(targetLocale);
+        let claimed = false;
+        try {
+            return await fn(targetLocale, (wanted) => { claimed = true; return budget.claim(slot, wanted); });
+        }
+        finally {
+            if (!claimed)
+                void budget.claim(slot, 0);
+        }
+    };
+    const { results: localeResults, errors: localeErrors } = await (0, concurrent_map_1.concurrentMap)(localeTasks, withBudget(async (targetLocale, claimBudget) => {
         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;
@@ -269,6 +287,7 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
                 tmHits: 0,
                 metadata: {},
                 failures: {},
+                skippedForBudget: [],
                 error: null,
             };
         }
@@ -276,7 +295,7 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
         // 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 translationResult = await translateEntries(entriesToTranslate, sourceLangCode, targetLangCode, projectId, onProgress, glossary, targetLocale, cacheProvider, byokConfig, contextMap, extractionContextMap, hasBrandVoiceInPrompt ? (brandVoice || undefined) : undefined, dryRun, forceTranslation, providers, rulesComplete, options, claimBudget);
         const entriesResult = translationResult.result;
         const batchStats = translationResult.stats;
         const batchMetadata = translationResult.metadata;
@@ -284,10 +303,13 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
         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 };
+            // (Not an error when the run's budget simply didn't reach this locale.)
+            if (Object.keys(keyFailures).length > 0 || translationResult.skippedForBudget.length === 0) {
+                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, skippedForBudget: translationResult.skippedForBudget, error: null };
         }
         let translatedEntries = entriesResult;
         // Post-hoc brand voice polish only for the NLLB service; LLM
@@ -355,15 +377,18 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
             tmHits: batchStats.tmHits,
             metadata: batchMetadata,
             failures: keyFailures,
+            skippedForBudget: translationResult.skippedForBudget,
             error: null,
         };
-    }, TRANSLATE_CONCURRENCY);
+    }), 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 });
         }
+        for (const key of r.skippedForBudget ?? [])
+            skippedForBudget.push({ key, locale: r.locale });
         if (r.error) {
             errors.push({ locale: r.locale, error: r.error });
         }
@@ -385,13 +410,19 @@ async function translateLocales(workspace, sourceLocale, targetLocales, forceTra
     if (byokConfig && (errors.length > 0 || localeErrors.length > 0)) {
         throw localeErrors.length > 0 ? localeErrors[0] : new Error(errors[0].error);
     }
+    if (skippedForBudget.length > 0) {
+        logger_1.engineLogger.warn('Translation budget reached; remaining strings are left for the next run', {
+            maxTranslations: options.maxTranslations,
+            skipped: skippedForBudget.length,
+        });
+    }
     return {
-        translation: { locales, errors, failures },
+        translation: { locales, errors, failures, skippedForBudget },
         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 = {}) {
+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 = {}, claimBudget) {
     const result = {};
     const metadata = {};
     const keys = Object.keys(entries);
@@ -546,6 +577,7 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
         });
     }
     const failures = {};
+    const skippedForBudget = [];
     // 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.
@@ -618,6 +650,14 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
                     : undefined,
             });
         }
+        // 1b. The run's budget: only as many keys as it covers go to the
+        //     translator (in source order). The rest get no value, like a failed
+        //     key: not in the locale file or lockfile, so the next run retries them.
+        if (claimBudget) {
+            const granted = await claimBudget(prepared.length);
+            for (const entry of prepared.splice(granted))
+                skippedForBudget.push(entry.key);
+        }
         // 2. Translate in batches; judge every key independently.
         const outcomes = new Map();
         const judge = (entry, keyResult, nllb = !isLlm) => {
@@ -970,7 +1010,7 @@ async function translateEntries(entries, sourceLang, targetLang, projectId, onPr
             meta.qa = [...(meta.qa ?? []), ...notes];
         metadata[key] = meta;
     }
-    return { result, stats: { tmHits }, metadata, failures };
+    return { result, stats: { tmHits }, metadata, failures, skippedForBudget };
 }
 /**
  * Persist translations to the project owner's TM. Never throws: a TM failure