@babelize/engine 0.2.1 → 0.3.0

package/dist/detection/i18n.d.ts

@@ -0,0 +1,19 @@
+import type { RepoFiles } from './stack';
+export type I18nLibraryId = 'next-intl' | 'next-i18next' | 'react-i18next' | 'i18next' | 'vue-i18n' | 'react-intl' | 'lingui' | 'django';
+export declare const I18N_LIBRARY_NAMES: Record<I18nLibraryId, string>;
+export type SourceLanguageBasis = 'config' | 'files' | 'default';
+export interface DetectedI18n {
+    library: {
+        id: I18nLibraryId;
+        name: string;
+    } | null;
+    /** Locale codes the repo already has files for, as written (en, pt-BR, zh_Hant). */
+    locales: string[];
+    /** Where the locale files live, e.g. "messages" or "public/locales". */
+    localeDir: string | null;
+    sourceLanguage: {
+        code: string;
+        basis: SourceLanguageBasis;
+    };
+}
+export declare function detectI18n(files: RepoFiles, framework?: string): Promise<DetectedI18n>;

package/dist/detection/i18n.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18N_LIBRARY_NAMES = void 0;
+exports.detectI18n = detectI18n;
+/**
+ * What a repository already has for i18n, read from a file listing and a few
+ * small files (no clone): the i18n library, existing locale files, and the
+ * source language. Runs on the same `RepoFiles` as `detectStack`, so the
+ * new-project flow can say "Next.js · English · next-intl detected" and
+ * pre-select the languages the repo already ships.
+ */
+const locale_files_1 = require("../qa/locale-files");
+exports.I18N_LIBRARY_NAMES = {
+    'next-intl': 'next-intl',
+    'next-i18next': 'next-i18next',
+    'react-i18next': 'react-i18next',
+    i18next: 'i18next',
+    'vue-i18n': 'vue-i18n',
+    'react-intl': 'react-intl',
+    lingui: 'Lingui',
+    django: 'Django i18n',
+};
+/** Most specific first: next-i18next depends on react-i18next, which depends on i18next. */
+const LIBRARY_DEPS = [
+    ['next-intl', ['next-intl']],
+    ['next-i18next', ['next-i18next']],
+    ['vue-i18n', ['vue-i18n', '@nuxtjs/i18n']],
+    ['react-i18next', ['react-i18next']],
+    ['react-intl', ['react-intl']],
+    ['lingui', ['@lingui/core', '@lingui/react']],
+    ['i18next', ['i18next']],
+];
+const IGNORED = /(?:^|\/)(?:node_modules|\.git|vendor|dist|build|\.next|out|coverage|__tests__|__fixtures__|fixtures|tests?|e2e)\//;
+/** Files that commonly declare the default locale, checked in this order. */
+const CONFIG_FILE = /(?:^|\/)(?:i18n(?:\/(?:routing|request|config|index))?|i18n\.config|next\.config|next-i18next\.config|nuxt\.config|src\/i18n(?:\/index)?|src\/plugins\/i18n|lingui\.config)\.(?:[cm]?[jt]s|json)$/;
+/** defaultLocale: 'de', fallbackLng: "fr", sourceLocale: 'en', locale: 'en' (vue-i18n createI18n). */
+const DEFAULT_LOCALE_PATTERNS = [
+    /\bdefaultLocale\s*[:=]\s*['"`]([A-Za-z_-]{2,12})['"`]/,
+    /\bsourceLocale\s*[:=]\s*['"`]([A-Za-z_-]{2,12})['"`]/,
+    /\bfallbackLng\s*[:=]\s*['"`]([A-Za-z_-]{2,12})['"`]/,
+    /\bfallbackLocale\s*[:=]\s*['"`]([A-Za-z_-]{2,12})['"`]/,
+];
+const DJANGO_LANGUAGE_CODE = /^\s*LANGUAGE_CODE\s*=\s*['"]([A-Za-z_-]{2,12})['"]/m;
+/** Django: locale/<code>/LC_MESSAGES/django.po */
+const DJANGO_PO = /(?:^|\/)locale\/([A-Za-z_-]{2,12})\/LC_MESSAGES\/django\.po$/;
+function depth(p) {
+    return p.split('/').length - 1;
+}
+async function readDeps(files, paths) {
+    const pkgs = paths
+        .filter((p) => (p === 'package.json' || p.endsWith('/package.json')) && depth(p) <= 2)
+        .sort((a, b) => depth(a) - depth(b))
+        .slice(0, 6);
+    const deps = new Set();
+    for (const p of pkgs) {
+        const raw = await files.read(p);
+        if (!raw)
+            continue;
+        try {
+            const pkg = JSON.parse(raw);
+            for (const name of Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }))
+                deps.add(name);
+        }
+        catch {
+            // not JSON: skip
+        }
+    }
+    return deps;
+}
+/** "en-us" (Django) → "en-US"; "pt_BR" stays as written. */
+function tidyCode(code) {
+    const m = /^([a-z]{2,3})-([a-z]{2})$/.exec(code);
+    return m ? `${m[1]}-${m[2].toUpperCase()}` : code;
+}
+async function detectI18n(files, framework) {
+    const paths = files.paths.filter((p) => !IGNORED.test(p));
+    // Library
+    let library = null;
+    if (framework === 'django') {
+        library = { id: 'django', name: exports.I18N_LIBRARY_NAMES.django };
+    }
+    else {
+        const deps = await readDeps(files, paths);
+        const found = LIBRARY_DEPS.find(([, names]) => names.some((n) => deps.has(n)));
+        if (found)
+            library = { id: found[0], name: exports.I18N_LIBRARY_NAMES[found[0]] };
+    }
+    // Existing locale files: the set with the most locales wins.
+    let locales = [];
+    let localeDir = null;
+    let largestByLocale = new Map();
+    const sets = (0, locale_files_1.groupLocaleFiles)(paths);
+    if (sets.length > 0) {
+        const best = sets.reduce((a, b) => (Object.keys(b.files).length > Object.keys(a.files).length ? b : a));
+        locales = Object.keys(best.files).sort();
+        localeDir = best.dir;
+        if (files.size) {
+            largestByLocale = new Map(locales.map((l) => [l, best.files[l].reduce((sum, f) => sum + (files.size(f) ?? 0), 0)]));
+        }
+    }
+    else {
+        const po = paths.map((p) => DJANGO_PO.exec(p)).filter((m) => !!m);
+        if (po.length > 0) {
+            locales = [...new Set(po.map((m) => m[1]))].sort();
+            localeDir = po[0][0].split('/').slice(0, -3).join('/') || '.';
+        }
+    }
+    // Source language: declared in config, else inferred from the locale files.
+    let sourceLanguage = { code: 'en', basis: 'default' };
+    const configCandidates = paths
+        .filter((p) => CONFIG_FILE.test(p) && depth(p) <= 3)
+        .sort((a, b) => depth(a) - depth(b))
+        .slice(0, 6);
+    if (framework === 'django') {
+        configCandidates.unshift(...paths.filter((p) => /(?:^|\/)settings(?:\/base)?\.py$/.test(p) && depth(p) <= 3).slice(0, 2));
+    }
+    for (const p of configCandidates) {
+        const content = await files.read(p);
+        if (!content)
+            continue;
+        const m = p.endsWith('.py')
+            ? DJANGO_LANGUAGE_CODE.exec(content)
+            : DEFAULT_LOCALE_PATTERNS.map((re) => re.exec(content)).find(Boolean);
+        const code = m?.[1] ? tidyCode(m[1]) : null;
+        if (code && (0, locale_files_1.isLocaleCode)(code)) {
+            sourceLanguage = { code, basis: 'config' };
+            break;
+        }
+    }
+    if (sourceLanguage.basis === 'default' && locales.length > 0) {
+        if (locales.length === 1) {
+            sourceLanguage = { code: locales[0], basis: 'files' };
+        }
+        else if (locales.some((l) => l === 'en' || l.startsWith('en-') || l.startsWith('en_'))) {
+            sourceLanguage = { code: locales.find((l) => l === 'en') ?? locales.find((l) => l.startsWith('en')), basis: 'files' };
+        }
+        else if (largestByLocale.size > 0) {
+            // The source usually has every key: the biggest file set.
+            const [code] = [...largestByLocale.entries()].reduce((a, b) => (b[1] > a[1] ? b : a));
+            sourceLanguage = { code, basis: 'files' };
+        }
+    }
+    return { library, locales, localeDir, sourceLanguage };
+}

package/dist/detection/stack.d.ts

@@ -32,6 +32,8 @@ export interface RepoFiles {
     read(relPath: string): Promise<string | null>;
     /** The listing is incomplete (very large repository). */
     truncated?: boolean;
+    /** File size in bytes, when the listing knows it. */
+    size?(relPath: string): number | undefined;
 }
 export declare const FRAMEWORK_DISPLAY_NAMES: Record<string, string>;
 /** Does a Python dependency file list Django itself (not just django-* add-ons)? */

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from './providers';
 export { runWithEngineLogger, setEngineLogger } from './utils/logger';
 export type { EngineLogger, LogContext } from './utils/logger';
 export * from './modules/lockfile';
+export { applyTranslationOverrides, setLocaleValue, type OverrideReport, type TranslationOverride } from './modules/overrides';
 export * from './modules/translator/language-codes';
 export type { MemoryEntry, FuzzyMatch, MemoryLookupResult } from './modules/translator/memory/types';
 export { matchFromMemory } from './modules/translator/memory/memory-matcher';
@@ -26,8 +27,10 @@ export type { SyncDetectionResult, SyncDetectedString, SyncMissingLocaleKey } fr
 export type { TranslationEntry, WorkspaceInfo } from './runtime/types';
 export { addBabelToHistory, detectProjectInfo, getBabelizeSummary, getProjectInfo, saveCachedStrings, saveProjectConfig, } from './utils/metadata';
 export type { BabelHistoryEntry, ExtractedStringEntry, ProjectInfo } from './utils/metadata';
-export { detectStack, localRepoFiles, FRAMEWORK_DISPLAY_NAMES } from './detection/stack';
+export { detectStack, localRepoFiles, FRAMEWORK_DISPLAY_NAMES, SUPPORTED_SUMMARY } from './detection/stack';
 export type { DetectedStack, RepoFiles, StackFramework, PackageManagerId } from './detection/stack';
+export { detectI18n, I18N_LIBRARY_NAMES } from './detection/i18n';
+export type { DetectedI18n, I18nLibraryId, SourceLanguageBasis } from './detection/i18n';
 export { parseCode } from './utils/ast-helpers';
 export { extractPlaceholders, hasICUSyntax, hashString, protectPlaceholders, restorePlaceholders, } from './utils/string-utils';
 export { sanitizeTranslation, validateRawTokens } from './utils/translation-sanitizer';

package/dist/index.js

@@ -21,8 +21,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.analyzeWorkspace = exports.analyzeProject = exports.localeExtension = exports.getCircuitBreaker = exports.CircuitState = exports.CircuitBreaker = exports.validateBatchQuality = exports.validateTranslationQuality = exports.translatorLoadBalancer = exports.warmupTranslator = exports.checkTranslatorHealth = exports.callTranslator = exports.requiredPluralCategories = exports.parseIcu = exports.isIcuMessage = exports.compareIcuMessages = exports.sameProtectedSpans = exports.restoreText = exports.protectText = exports.hasNothingToTranslate = exports.checkTokens = exports.validateRawTokens = exports.sanitizeTranslation = exports.restorePlaceholders = exports.protectPlaceholders = exports.hashString = exports.hasICUSyntax = exports.extractPlaceholders = exports.parseCode = exports.FRAMEWORK_DISPLAY_NAMES = exports.localRepoFiles = exports.detectStack = exports.saveProjectConfig = exports.saveCachedStrings = exports.getProjectInfo = exports.getBabelizeSummary = exports.detectProjectInfo = exports.addBabelToHistory = exports.formatSyncNotificationMessage = exports.detectSyncIssues = exports.matchFromMemory = exports.setEngineLogger = exports.runWithEngineLogger = exports.validateWorkspace = exports.scanKeyReferences = exports.RunAbortedError = exports.validateEngineConfigV2 = exports.runEngineV2 = exports.loadBabelizeConfig = exports.BabelizeEngine = void 0;
-exports.TRANSLATION_CACHE_TTL_SECONDS = exports.translationCacheKey = exports.hashText = exports.readProjectLocaleConfig = exports.localeIssueFile = exports.checkProjectLocales = exports.ReviewError = exports.reviewLocaleChanges = exports.loadLocale = exports.isLocaleCode = exports.isIgnoredLocalePath = exports.groupLocaleFiles = exports.findLocaleFileSets = exports.DEFAULT_LOCALE_IGNORE_DIRS = exports.glossaryFingerprint = exports.normalizeGlossary = exports.localeValue = exports.containsTerm = exports.canonicalizeLocaleKeys = exports.canonicalLocale = exports.tallyLocaleIssues = exports.flattenLocaleMessages = exports.checkLocalePair = exports.frameworkSupport = void 0;
+exports.CircuitBreaker = exports.validateBatchQuality = exports.validateTranslationQuality = exports.translatorLoadBalancer = exports.warmupTranslator = exports.checkTranslatorHealth = exports.callTranslator = exports.requiredPluralCategories = exports.parseIcu = exports.isIcuMessage = exports.compareIcuMessages = exports.sameProtectedSpans = exports.restoreText = exports.protectText = exports.hasNothingToTranslate = exports.checkTokens = exports.validateRawTokens = exports.sanitizeTranslation = exports.restorePlaceholders = exports.protectPlaceholders = exports.hashString = exports.hasICUSyntax = exports.extractPlaceholders = exports.parseCode = exports.I18N_LIBRARY_NAMES = exports.detectI18n = exports.SUPPORTED_SUMMARY = exports.FRAMEWORK_DISPLAY_NAMES = exports.localRepoFiles = exports.detectStack = exports.saveProjectConfig = exports.saveCachedStrings = exports.getProjectInfo = exports.getBabelizeSummary = exports.detectProjectInfo = exports.addBabelToHistory = exports.formatSyncNotificationMessage = exports.detectSyncIssues = exports.matchFromMemory = exports.setLocaleValue = exports.applyTranslationOverrides = exports.setEngineLogger = exports.runWithEngineLogger = exports.validateWorkspace = exports.scanKeyReferences = exports.RunAbortedError = exports.validateEngineConfigV2 = exports.runEngineV2 = exports.loadBabelizeConfig = exports.BabelizeEngine = void 0;
+exports.TRANSLATION_CACHE_TTL_SECONDS = exports.translationCacheKey = exports.hashText = exports.readProjectLocaleConfig = exports.localeIssueFile = exports.checkProjectLocales = exports.ReviewError = exports.reviewLocaleChanges = exports.loadLocale = exports.isLocaleCode = exports.isIgnoredLocalePath = exports.groupLocaleFiles = exports.findLocaleFileSets = exports.DEFAULT_LOCALE_IGNORE_DIRS = exports.glossaryFingerprint = exports.normalizeGlossary = exports.localeValue = exports.containsTerm = exports.canonicalizeLocaleKeys = exports.canonicalLocale = exports.tallyLocaleIssues = exports.flattenLocaleMessages = exports.checkLocalePair = exports.frameworkSupport = exports.analyzeWorkspace = exports.analyzeProject = exports.localeExtension = exports.getCircuitBreaker = exports.CircuitState = void 0;
 var BabelizeEngine_1 = require("./BabelizeEngine");
 Object.defineProperty(exports, "BabelizeEngine", { enumerable: true, get: function () { return BabelizeEngine_1.BabelizeEngine; } });
 var config_1 = require("./config");
@@ -46,6 +46,9 @@ Object.defineProperty(exports, "runWithEngineLogger", { enumerable: true, get: f
 Object.defineProperty(exports, "setEngineLogger", { enumerable: true, get: function () { return logger_1.setEngineLogger; } });
 // ── Pipeline pieces the backend uses directly ────────────────
 __exportStar(require("./modules/lockfile"), exports);
+var overrides_1 = require("./modules/overrides");
+Object.defineProperty(exports, "applyTranslationOverrides", { enumerable: true, get: function () { return overrides_1.applyTranslationOverrides; } });
+Object.defineProperty(exports, "setLocaleValue", { enumerable: true, get: function () { return overrides_1.setLocaleValue; } });
 __exportStar(require("./modules/translator/language-codes"), exports);
 var memory_matcher_1 = require("./modules/translator/memory/memory-matcher");
 Object.defineProperty(exports, "matchFromMemory", { enumerable: true, get: function () { return memory_matcher_1.matchFromMemory; } });
@@ -64,6 +67,10 @@ var stack_1 = require("./detection/stack");
 Object.defineProperty(exports, "detectStack", { enumerable: true, get: function () { return stack_1.detectStack; } });
 Object.defineProperty(exports, "localRepoFiles", { enumerable: true, get: function () { return stack_1.localRepoFiles; } });
 Object.defineProperty(exports, "FRAMEWORK_DISPLAY_NAMES", { enumerable: true, get: function () { return stack_1.FRAMEWORK_DISPLAY_NAMES; } });
+Object.defineProperty(exports, "SUPPORTED_SUMMARY", { enumerable: true, get: function () { return stack_1.SUPPORTED_SUMMARY; } });
+var i18n_1 = require("./detection/i18n");
+Object.defineProperty(exports, "detectI18n", { enumerable: true, get: function () { return i18n_1.detectI18n; } });
+Object.defineProperty(exports, "I18N_LIBRARY_NAMES", { enumerable: true, get: function () { return i18n_1.I18N_LIBRARY_NAMES; } });
 var ast_helpers_1 = require("./utils/ast-helpers");
 Object.defineProperty(exports, "parseCode", { enumerable: true, get: function () { return ast_helpers_1.parseCode; } });
 var string_utils_1 = require("./utils/string-utils");

package/dist/local/hosted-provider.d.ts

@@ -2,7 +2,8 @@ import type { KeyResult, TranslationBatchRequest, TranslationProvider } from '..
 /**
  * Babelize-hosted translation for `babelize translate`: a TranslationProvider
  * that sends the engine's already placeholder-protected strings (never code)
- * to POST {apiUrl}/v1/translate/batch with a Babelize API key. The engine
+ * to POST {apiUrl}/v1/translate/batch with a Babelize API key or a signed-in
+ * CLI session (the endpoint accepts both and bills the same account). The engine
  * still validates every result and runs its repair retry locally; model,
  * quota and credits are decided by the server.
  */
@@ -36,8 +37,19 @@ export declare class HostedTranslationError extends Error {
     get fatal(): boolean;
 }
 export interface HostedProviderOptions {
-    /** Babelize API key (bblz_sk_…). Never printed. */
+    /** Babelize API key (bblz_sk_…) or a session access token. Never printed. */
     apiKey: string;
+    /**
+     * What `apiKey` is, for the message when it's rejected: an API key from
+     * BABELIZE_API_KEY (default) or the CLI's signed-in session.
+     */
+    credential?: 'api_key' | 'session';
+    /**
+     * Called once when a request is rejected with 401: return a fresh token
+     * (a session refresh) to retry with it, or null to give up. Sessions expire
+     * during long runs; API keys don't, so API-key callers leave this out.
+     */
+    refreshToken?: () => Promise<string | null>;
     /** e.g. https://api.babelize.co/api */
     apiUrl: string;
     fetch?: typeof fetch;
@@ -57,10 +69,26 @@ export declare function parseRetryAfterMs(value: string | null): number | undefi
 export declare class HostedTranslationProvider implements TranslationProvider {
     /** Model the server reported (X-Babelize-Model), once a request succeeded. */
     model?: string;
+    /**
+     * True when the server translates with NLLB rather than an LLM: the engine
+     * then splits ICU messages and multi-line text and protects glossary terms
+     * before sending, as it does for cloud runs. Set by detectCapabilities().
+     */
+    plainText: boolean;
     /** Set once a request fails in a way no retry can fix (bad key, no credits). */
     fatalError?: HostedTranslationError;
     private readonly opts;
+    /** The token in use; replaced when a session is refreshed. */
+    private token;
+    /** In-flight refresh, shared by concurrent batches that all got a 401. */
+    private refreshing?;
     constructor(options: HostedProviderOptions);
+    /**
+     * Ask the server what serves translation (GET /v1/translate/capabilities)
+     * before a run, so requests are shaped for it. A server without the endpoint
+     * (older) or any failure keeps the LLM shape; the run itself reports errors.
+     */
+    detectCapabilities(): Promise<void>;
     translateBatch(request: TranslationBatchRequest): Promise<KeyResult[]>;
     private post;
     private backoff;

package/dist/local/hosted-provider.js

@@ -8,7 +8,8 @@ const types_1 = require("@babelize/types");
 /**
  * Babelize-hosted translation for `babelize translate`: a TranslationProvider
  * that sends the engine's already placeholder-protected strings (never code)
- * to POST {apiUrl}/v1/translate/batch with a Babelize API key. The engine
+ * to POST {apiUrl}/v1/translate/batch with a Babelize API key or a signed-in
+ * CLI session (the endpoint accepts both and bills the same account). The engine
  * still validates every result and runs its repair retry locally; model,
  * quota and credits are decided by the server.
  */
@@ -48,6 +49,13 @@ function parseRetryAfterMs(value) {
 }
 class HostedTranslationProvider {
     constructor(options) {
+        /**
+         * True when the server translates with NLLB rather than an LLM: the engine
+         * then splits ICU messages and multi-line text and protects glossary terms
+         * before sending, as it does for cloud runs. Set by detectCapabilities().
+         */
+        this.plainText = false;
+        this.token = options.apiKey;
         this.opts = {
             fetch: globalThis.fetch.bind(globalThis),
             maxRetries: 3,
@@ -59,6 +67,31 @@ class HostedTranslationProvider {
             apiUrl: options.apiUrl.replace(/\/+$/, ''),
         };
     }
+    /**
+     * Ask the server what serves translation (GET /v1/translate/capabilities)
+     * before a run, so requests are shaped for it. A server without the endpoint
+     * (older) or any failure keeps the LLM shape; the run itself reports errors.
+     */
+    async detectCapabilities() {
+        try {
+            const res = await this.opts.fetch(`${this.opts.apiUrl}/v1/translate/capabilities`, {
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    ...(this.opts.userAgent ? { 'User-Agent': this.opts.userAgent } : {}),
+                },
+                signal: AbortSignal.timeout(15000),
+            });
+            if (!res.ok)
+                return;
+            const body = (await res.json());
+            this.plainText = body.plainText === true;
+            if (body.model)
+                this.model ?? (this.model = body.model);
+        }
+        catch {
+            // keep the defaults
+        }
+    }
     async translateBatch(request) {
         // Strings over the server's limits never leave the machine: they fail
         // locally, and the rest of the batch is still sent.
@@ -122,6 +155,7 @@ class HostedTranslationProvider {
         // replays it instead of translating and charging again.
         const idempotencyKey = (0, node_crypto_1.randomUUID)();
         let attempt = 0;
+        let refreshed = false;
         for (;;) {
             let res;
             try {
@@ -129,7 +163,7 @@ class HostedTranslationProvider {
                     method: 'POST',
                     headers: {
                         'Content-Type': 'application/json',
-                        Authorization: `Bearer ${this.opts.apiKey}`,
+                        Authorization: `Bearer ${this.token}`,
                         'Idempotency-Key': idempotencyKey,
                         ...(this.opts.userAgent ? { 'User-Agent': this.opts.userAgent } : {}),
                     },
@@ -162,6 +196,17 @@ class HostedTranslationProvider {
                 this.model = res.headers.get(exports.HOSTED_MODEL_HEADER) ?? this.model;
                 return Array.isArray(data.results) ? data.results : [];
             }
+            // An expired session: refresh it once and try again with the same key.
+            if (res.status === 401 && this.opts.refreshToken && !refreshed) {
+                refreshed = true;
+                const sent = this.token;
+                this.refreshing ?? (this.refreshing = this.opts.refreshToken().finally(() => { this.refreshing = undefined; }));
+                const fresh = this.token !== sent ? this.token : await this.refreshing;
+                if (fresh) {
+                    this.token = fresh;
+                    continue;
+                }
+            }
             if (RETRYABLE_STATUS.has(res.status) && attempt < this.opts.maxRetries && !(await isHostedOff(res))) {
                 const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
                 await this.opts.sleep(Math.min(retryAfter ?? this.backoff(attempt), this.opts.maxRetryAfterMs));
@@ -183,7 +228,9 @@ class HostedTranslationProvider {
         switch (res.status) {
             case 401:
             case 403:
-                return new HostedTranslationError(`BABELIZE_API_KEY was rejected (${res.status}). Create a new key at ${exports.API_KEYS_URL} and set BABELIZE_API_KEY.`, 'hosted_auth', res.status);
+                return new HostedTranslationError(this.opts.credential === 'session'
+                    ? `Your Babelize sign-in was rejected (${res.status}). Sign in again with \`babelize auth login\`, then re-run.`
+                    : `BABELIZE_API_KEY was rejected (${res.status}). Create a new key at ${exports.API_KEYS_URL} and set BABELIZE_API_KEY.`, 'hosted_auth', res.status);
             case 402:
                 return new HostedTranslationError(payload?.message ??
                     `Your Babelize account is out of AI credits. Top up or upgrade at ${exports.BILLING_URL}, or use your own LLM key (e.g. set ANTHROPIC_API_KEY).`, 'hosted_credits', 402);

package/dist/local/translate-core.js

@@ -283,6 +283,10 @@ async function runScoped(opts, deps, engineLog, state) {
     if (!opts.byok && !translator) {
         throw new LocalTranslateError('No translation provider configured.', 'no_translator');
     }
+    // Shape requests for what the server translates with (NLLB needs ICU and
+    // multi-line text split and glossary terms protected; an LLM doesn't).
+    if (deps.hosted)
+        await deps.hosted.detectCapabilities();
     const files = await listProjectFiles(projectDir);
     const temp = await (0, workspace_copy_1.createTempCopy)(projectDir, { files, tmpRoot: deps.tmpRoot });
     try {

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

@@ -1,3 +1,3 @@
 export { hashSourceString } from './hasher';
 export { type LockfileData, type LockfileEntry, type LockfilePartition, type LockfileStats, type PartitionedKey, createEmptyLockfile, } from './schema';
-export { buildKeysToTranslateByTargetLocale, clearLockfile, removeLocaleFromLockfile, collectCachedTranslations, computeLockfileStats, getLockfilePath, loadLockfile, partitionKeys, saveLockfile, updateLockfile, lockfileChanged, dropFailedTranslations, isStalePseudoEntry, glossaryChanged, type LockfileReadOptions, } from './lockfile-manager';
+export { buildKeysToTranslateByTargetLocale, clearLockfile, removeLocaleFromLockfile, removeLockfileEntries, collectCachedTranslations, computeLockfileStats, getLockfilePath, loadLockfile, partitionKeys, saveLockfile, updateLockfile, lockfileChanged, dropFailedTranslations, isStalePseudoEntry, glossaryChanged, type LockfileReadOptions, } from './lockfile-manager';

package/dist/modules/lockfile/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.glossaryChanged = exports.isStalePseudoEntry = exports.dropFailedTranslations = exports.lockfileChanged = exports.updateLockfile = exports.saveLockfile = exports.partitionKeys = exports.loadLockfile = exports.getLockfilePath = exports.computeLockfileStats = exports.collectCachedTranslations = exports.removeLocaleFromLockfile = exports.clearLockfile = exports.buildKeysToTranslateByTargetLocale = exports.createEmptyLockfile = exports.hashSourceString = void 0;
+exports.glossaryChanged = exports.isStalePseudoEntry = exports.dropFailedTranslations = exports.lockfileChanged = exports.updateLockfile = exports.saveLockfile = exports.partitionKeys = exports.loadLockfile = exports.getLockfilePath = exports.computeLockfileStats = exports.collectCachedTranslations = exports.removeLockfileEntries = exports.removeLocaleFromLockfile = exports.clearLockfile = exports.buildKeysToTranslateByTargetLocale = exports.createEmptyLockfile = exports.hashSourceString = void 0;
 var hasher_1 = require("./hasher");
 Object.defineProperty(exports, "hashSourceString", { enumerable: true, get: function () { return hasher_1.hashSourceString; } });
 var schema_1 = require("./schema");
@@ -9,6 +9,7 @@ var lockfile_manager_1 = require("./lockfile-manager");
 Object.defineProperty(exports, "buildKeysToTranslateByTargetLocale", { enumerable: true, get: function () { return lockfile_manager_1.buildKeysToTranslateByTargetLocale; } });
 Object.defineProperty(exports, "clearLockfile", { enumerable: true, get: function () { return lockfile_manager_1.clearLockfile; } });
 Object.defineProperty(exports, "removeLocaleFromLockfile", { enumerable: true, get: function () { return lockfile_manager_1.removeLocaleFromLockfile; } });
+Object.defineProperty(exports, "removeLockfileEntries", { enumerable: true, get: function () { return lockfile_manager_1.removeLockfileEntries; } });
 Object.defineProperty(exports, "collectCachedTranslations", { enumerable: true, get: function () { return lockfile_manager_1.collectCachedTranslations; } });
 Object.defineProperty(exports, "computeLockfileStats", { enumerable: true, get: function () { return lockfile_manager_1.computeLockfileStats; } });
 Object.defineProperty(exports, "getLockfilePath", { enumerable: true, get: function () { return lockfile_manager_1.getLockfilePath; } });

package/dist/modules/lockfile/lockfile-manager.d.ts

@@ -32,6 +32,15 @@ export declare function clearLockfile(projectId: string, dataDir?: string): Prom
  * Used when a language is removed from a project so re-adding it
  * triggers fresh translation instead of resurrecting stale cache.
  */
+/**
+ * Forget the stored translation of some (key, locale) pairs, so the next run
+ * translates them again (a dashboard edit that was reverted). Other locales
+ * of the key stay.
+ */
+export declare function removeLockfileEntries(projectId: string, entries: Array<{
+    key: string;
+    locale: string;
+}>, dataDir?: string): Promise<number>;
 export declare function removeLocaleFromLockfile(projectId: string, localeCode: string, dataDir?: string): Promise<void>;
 /**
  * Partition generated keys into unchanged / new / changed / missingLocales

package/dist/modules/lockfile/lockfile-manager.js

@@ -38,6 +38,7 @@ exports.getLockfilePath = getLockfilePath;
 exports.loadLockfile = loadLockfile;
 exports.saveLockfile = saveLockfile;
 exports.clearLockfile = clearLockfile;
+exports.removeLockfileEntries = removeLockfileEntries;
 exports.removeLocaleFromLockfile = removeLocaleFromLockfile;
 exports.glossaryChanged = glossaryChanged;
 exports.isStalePseudoEntry = isStalePseudoEntry;
@@ -242,6 +243,44 @@ async function clearLockfile(projectId, dataDir) {
  * Used when a language is removed from a project so re-adding it
  * triggers fresh translation instead of resurrecting stale cache.
  */
+/**
+ * Forget the stored translation of some (key, locale) pairs, so the next run
+ * translates them again (a dashboard edit that was reverted). Other locales
+ * of the key stay.
+ */
+async function removeLockfileEntries(projectId, entries, dataDir) {
+    const lockfilePath = getLockfilePath(projectId, dataDir);
+    if (entries.length === 0 || !(await fs.pathExists(lockfilePath)))
+        return 0;
+    const lockDir = lockfilePath + '.lock';
+    await acquireLock(lockDir);
+    try {
+        // Read under the lock: a run saving meanwhile must not be lost.
+        const lockfile = await loadLockfile(projectId, dataDir);
+        let removed = 0;
+        for (const { key, locale } of entries) {
+            const entry = lockfile.keys[key];
+            if (!entry || !(locale in entry.languages))
+                continue;
+            delete entry.languages[locale];
+            if (entry.metadata)
+                delete entry.metadata[locale];
+            if (Object.keys(entry.languages).length === 0)
+                delete lockfile.keys[key];
+            removed++;
+        }
+        if (removed > 0) {
+            lockfile.updatedAt = new Date().toISOString();
+            const tmpPath = lockfilePath + '.tmp';
+            await fs.writeJson(tmpPath, lockfile, { spaces: 2 });
+            await fs.rename(tmpPath, lockfilePath);
+        }
+        return removed;
+    }
+    finally {
+        await releaseLock(lockDir);
+    }
+}
 async function removeLocaleFromLockfile(projectId, localeCode, dataDir) {
     const lockfilePath = getLockfilePath(projectId, dataDir);
     try {
@@ -297,7 +336,8 @@ function glossaryChanged(entry, source, locale, options = {}) {
     if (!options.glossaryHash)
         return false;
     const meta = entry.metadata?.[locale];
-    if (meta?.external)
+    // The project's own files, or a dashboard edit: the glossary doesn't rewrite them.
+    if (meta?.external || meta?.manual)
         return false;
     return (meta?.glossaryHash ?? '') !== options.glossaryHash(source, locale);
 }
@@ -394,6 +434,8 @@ function pickLockfileMetadata(meta) {
         out.glossaryHash = meta.glossaryHash;
     if (meta.external === true)
         out.external = true;
+    if (meta.manual === true)
+        out.manual = true;
     return out;
 }
 function sameJson(a, b) {

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/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

package/dist/orchestrator.js

@@ -52,6 +52,7 @@ const finalization_1 = require("./modules/finalization");
 const lockfile_1 = require("./modules/lockfile");
 const file_utils_1 = require("./utils/file-utils");
 const key_usage_1 = require("./utils/key-usage");
+const overrides_1 = require("./modules/overrides");
 const not_injected_1 = require("./utils/not-injected");
 const language_codes_1 = require("./modules/translator/language-codes");
 const format_injection_1 = require("./modules/format-injection");
@@ -180,6 +181,8 @@ async function runEngineV2(config) {
         // (key, locale) translations the translator produced this run — the
         // billable work. Lockfile/TM/cache reuse and failures are excluded.
         let translatedThisRun = 0;
+        // (key, locale) pairs left for the next run: the run's maxTranslations ran out.
+        let skippedForBudget = 0;
         let keyUsage;
         let translationMetadata = {};
         if (config.projectId) {
@@ -239,6 +242,20 @@ async function runEngineV2(config) {
             // lack some locales (a newly added language): their existing locales are
             // still valid and must not drop out of the other locale files.
             const cachedTranslations = (0, lockfile_1.collectCachedTranslations)(lockfile, [...partition.unchanged, ...partition.missingLocales], config.targetLocales, lockfileRead);
+            // Dashboard edits (overrides), loaded before translating: a pair with a
+            // current edit is never sent to the translator (it would be thrown away).
+            let overrides = [];
+            if (config.providers?.overrides) {
+                try {
+                    overrides = await config.providers.overrides.getOverrides(config.projectId);
+                }
+                catch (err) {
+                    logger_1.engineLogger.warn('Could not load translation overrides; translating without them', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            const overridden = new Set(overrides.filter((o) => flatKeys[o.key] === o.sourceText).map((o) => `${o.locale}\u0000${o.key}`));
             config.onProgress?.('Translating to target locales...', 'translation', 'running');
             const translatorHealthy = await isTranslatorHealthy(config);
             if (!translatorHealthy) {
@@ -259,13 +276,19 @@ async function runEngineV2(config) {
             }
             else if (translatorHealthy) {
                 const keysToTranslateByLocale = (0, lockfile_1.buildKeysToTranslateByTargetLocale)(partition, config.targetLocales);
-                const result = await (0, translate_1.translateLocales)(workspace, localeHandling.sourceLocale, config.targetLocales, config.forceTranslation, config.dryRun, config.projectId, (msg) => config.onProgress?.(msg, 'translation', 'running'), keysToTranslateByLocale, config.providers?.cache, config.byok, contextMap, extractionContextMap, config.providers, { targetPlurals: icuOptions.targetPlurals, pluralValuePlaceholders: gettext?.pluralValuePlaceholders(), rules, progress: translationProgress });
+                if (overridden.size > 0) {
+                    for (const [locale, keys] of Object.entries(keysToTranslateByLocale)) {
+                        keysToTranslateByLocale[locale] = keys.filter((k) => !overridden.has(`${locale}\u0000${k}`));
+                    }
+                }
+                const result = await (0, translate_1.translateLocales)(workspace, localeHandling.sourceLocale, config.targetLocales, config.forceTranslation, config.dryRun, config.projectId, (msg) => config.onProgress?.(msg, 'translation', 'running'), keysToTranslateByLocale, config.providers?.cache, config.byok, contextMap, extractionContextMap, config.providers, { targetPlurals: icuOptions.targetPlurals, pluralValuePlaceholders: gettext?.pluralValuePlaceholders(), rules, progress: translationProgress, maxTranslations: config.maxTranslations });
                 translation = result.translation;
                 // A translation that wouldn't compile into the .po file is a failure, not output.
                 gettext?.validate(translation, flatKeys);
                 tmHits = result.stats.tmHits;
                 translationMetadata = result.metadata;
                 translatedThisRun = freshTranslations(translation, translationMetadata);
+                skippedForBudget = translation.skippedForBudget?.length ?? 0;
                 // Strings reused from the lockfile still make a good run: only fail
                 // when nothing at all is usable. Otherwise one string that keeps
                 // failing (and is retried every run) failed the whole project.
@@ -326,6 +349,24 @@ async function runEngineV2(config) {
                     locale.data._meta = { dir: (0, language_codes_1.isRTL)(locale.locale) ? 'rtl' : 'ltr', language: locale.locale };
                 }
             }
+            // Dashboard edits win over the lockfile and the translator (while their
+            // source text is unchanged); the lockfile marks them as manual.
+            let overrideReport;
+            if (overrides.length > 0) {
+                overrideReport = (0, overrides_1.applyTranslationOverrides)(translation.locales, flatKeys, overrides);
+                for (const { key, locale } of overrideReport.applied) {
+                    translationMetadata[locale] = { ...(translationMetadata[locale] ?? {}) };
+                    // Keep what the lockfile knew (glossary fingerprint, inTm): losing it would re-translate the key every run.
+                    // Not a fallback translation (that flag would drop it from the lockfile).
+                    const kept = { ...(lockfile.keys[key]?.metadata?.[locale] ?? {}), ...(translationMetadata[locale][key] ?? {}) };
+                    delete kept.fallback;
+                    translationMetadata[locale][key] = { ...kept, manual: true };
+                }
+                logger_1.engineLogger.info('Applied translation overrides', {
+                    applied: overrideReport.applied.length,
+                    replaced: overrideReport.replaced.length,
+                });
+            }
             // The translator wrote only this run's strings to disk; write the merged
             // locale (lockfile + new) so the workspace — which the download ZIP is
             // built from — has every translation, including fully cached locales.
@@ -384,6 +425,9 @@ async function runEngineV2(config) {
                 const previousLockfile = lockfile;
                 lockfile = (0, lockfile_1.updateLockfile)(lockfile, flatKeys, allTranslatedPerLocale, config.projectId, lockfileMetadata);
                 lockfile = (0, lockfile_1.dropFailedTranslations)(lockfile, translation.failures ?? []);
+                // Pairs the budget didn't cover are retried next run the same way
+                // (a changed key must not keep its old translation as current).
+                lockfile = (0, lockfile_1.dropFailedTranslations)(lockfile, translation.skippedForBudget ?? []);
                 // Backup-translator (NLLB) output is shipped in the locale file but not
                 // recorded as done, so the next run retries it with the AI translator.
                 lockfile = (0, lockfile_1.dropFailedTranslations)(lockfile, fallbackTranslations(translationMetadata));
@@ -403,8 +447,8 @@ async function runEngineV2(config) {
                 extraction, keyGeneration, localeHandling, translation,
                 config, startTime, workspace, allTranslatedPerLocale,
                 lockfileStats, tmHits, translationMetadata,
-                translatedThisRun, keyUsage,
-                formatStrings, frameworkConfig, gettext,
+                translatedThisRun, skippedForBudget, keyUsage,
+                formatStrings, frameworkConfig, gettext, overrideReport,
             });
             return result;
         }
@@ -429,7 +473,7 @@ async function runEngineV2(config) {
             config.onProgress?.(msg, 'translation', 'warning');
         }
         const translationResult = translatorHealthy
-            ? await (0, translate_1.translateLocales)(workspace, localeHandling.sourceLocale, config.targetLocales, config.forceTranslation, config.dryRun, config.projectId, (msg) => config.onProgress?.(msg, 'translation', 'running'), undefined, config.providers?.cache, config.byok, contextMap, extractionContextMap, config.providers, { targetPlurals: icuOptions.targetPlurals, pluralValuePlaceholders: gettext?.pluralValuePlaceholders(), progress: translationProgress })
+            ? await (0, translate_1.translateLocales)(workspace, localeHandling.sourceLocale, config.targetLocales, config.forceTranslation, config.dryRun, config.projectId, (msg) => config.onProgress?.(msg, 'translation', 'running'), undefined, config.providers?.cache, config.byok, contextMap, extractionContextMap, config.providers, { targetPlurals: icuOptions.targetPlurals, pluralValuePlaceholders: gettext?.pluralValuePlaceholders(), progress: translationProgress, maxTranslations: config.maxTranslations })
             : {
                 translation: {
                     locales: [],
@@ -443,6 +487,7 @@ async function runEngineV2(config) {
         tmHits = translationResult.stats.tmHits;
         translationMetadata = translationResult.metadata;
         translatedThisRun = freshTranslations(translation, translationMetadata);
+        skippedForBudget = translation.skippedForBudget?.length ?? 0;
         assertSomethingTranslated(translation);
         // Fail immediately when translation errors occurred — before injection/finalization
         if (translation.errors && translation.errors.length > 0) {
@@ -458,7 +503,7 @@ async function runEngineV2(config) {
             extraction, keyGeneration, localeHandling, translation,
             config, startTime, workspace, allTranslatedPerLocale,
             lockfileStats: undefined, tmHits, translationMetadata,
-            translatedThisRun, keyUsage,
+            translatedThisRun, skippedForBudget, keyUsage,
             formatStrings, frameworkConfig, gettext,
         });
         return result;
@@ -621,7 +666,7 @@ function mergeChangedFile(list, changed) {
     existing.hookAdded = existing.hookAdded || changed.hookAdded;
 }
 async function finalizePipeline(params) {
-    const { extraction, keyGeneration, localeHandling, translation, config, startTime, workspace, allTranslatedPerLocale, lockfileStats, tmHits, translationMetadata, formatStrings, frameworkConfig, translatedThisRun, keyUsage, gettext, } = params;
+    const { extraction, keyGeneration, localeHandling, translation, config, startTime, workspace, allTranslatedPerLocale, lockfileStats, tmHits, translationMetadata, formatStrings, frameworkConfig, translatedThisRun, skippedForBudget, keyUsage, gettext, overrideReport, } = params;
     const keyMapping = (0, keygen_1.createKeyMapping)(keyGeneration.keys);
     // Injection: AST-based i18n hook injection (skipped for frameworks like Django)
     let injection;
@@ -701,6 +746,8 @@ async function finalizePipeline(params) {
     config.onProgress?.('Generating summary...', 'summary', 'running');
     const { stats, warnings, diffs } = (0, summary_1.generateSummary)(extraction, keyGeneration, localeHandling, translation, injection, startTime, lockfileStats, tmHits);
     stats.translatedThisRun = Math.max(0, translatedThisRun);
+    if (skippedForBudget && skippedForBudget > 0)
+        stats.skippedForBudget = skippedForBudget;
     logger_1.engineLogger.info('Processing complete', stats);
     logger_1.engineLogger.debug('Readable summary', { summary: (0, summary_1.generateReadableSummary)(stats) });
     const allLocales = [localeHandling.sourceLocale, ...translation.locales];
@@ -723,5 +770,6 @@ async function finalizePipeline(params) {
             targets: allTranslatedPerLocale,
             metadata: translationMetadata,
         },
+        ...(overrideReport ? { overrides: overrideReport } : {}),
     };
 }

package/dist/providers/types.d.ts

@@ -1,6 +1,7 @@
 import type { TranslationEntry } from '../runtime/types';
 import type { MemoryEntry } from '../modules/translator/memory/types';
 import type { GlossaryEntryType } from '../modules/glossary/types';
+import type { TranslationOverride } from '../modules/overrides';
 /**
  * Everything the engine needs from the outside world, as interfaces. The
  * engine never imports a database or cache client: the cloud backend injects
@@ -129,6 +130,9 @@ export interface ProjectRulesStore {
     getGlossary(projectId: string): Promise<GlossaryRule[]>;
     getBrandVoice(projectId: string): Promise<string | null>;
 }
+export interface TranslationOverrideStore {
+    getOverrides(projectId: string): Promise<TranslationOverride[]>;
+}
 export interface TranslationCache {
     get(key: string): Promise<{
         hit: boolean;
@@ -150,4 +154,6 @@ export interface EngineProviders {
     memory?: TranslationMemoryStore;
     rules?: ProjectRulesStore;
     cache?: TranslationCache;
+    /** Translations edited in the dashboard; they win over every other source. */
+    overrides?: TranslationOverrideStore;
 }

package/dist/runtime/config.js

@@ -24,6 +24,7 @@ function validateEngineConfigV2(config) {
         confidenceThreshold,
         dryRun: config.dryRun ?? false,
         forceTranslation: config.forceTranslation ?? false,
+        maxTranslations: config.maxTranslations,
         onProgress: config.onProgress,
         signal: config.signal,
         projectId: config.projectId,

package/dist/runtime/types.d.ts

@@ -25,6 +25,15 @@ export interface EngineConfigV2 {
     dryRun: boolean;
     /** Force translation even if locale files exist */
     forceTranslation?: boolean;
+    /**
+     * Most (key, locale) pairs this run may send to the translator: the
+     * caller's credit budget. Pairs past it are left untranslated (not in the
+     * locale files or lockfile, so the next run picks them up) and counted in
+     * `stats.skippedForBudget`. Lockfile, translation-memory, cache and
+     * passthrough reuse never count against it. Languages are filled in
+     * `targetLocales` order, keys in source order. Undefined or negative: no cap.
+     */
+    maxTranslations?: number;
     /** Project ID for scoping lockfile/memory */
     projectId?: string;
     /**
@@ -266,6 +275,11 @@ export interface TranslationResult {
     }>;
     /** Keys with no translation for a locale this run (not written, retried next run). */
     failures?: TranslationFailure[];
+    /** (key, locale) pairs not sent to the translator because the run's `maxTranslations` ran out (retried next run). */
+    skippedForBudget?: Array<{
+        key: string;
+        locale: string;
+    }>;
 }
 export interface InjectionLocation {
     file: string;
@@ -339,6 +353,11 @@ export interface ProcessingStats {
      * and failed keys.
      */
     translatedThisRun?: number;
+    /**
+     * (key, locale) translations left for the next run because the run's
+     * `maxTranslations` budget ran out. Set only when some were skipped.
+     */
+    skippedForBudget?: number;
 }
 export interface NotInjectedString {
     file: string;
@@ -398,6 +417,8 @@ export interface EngineResultV2 {
         targets: Record<string, Record<string, string>>;
         metadata?: Record<string, Record<string, any>>;
     };
+    /** Dashboard edits this run applied, and those whose source text changed (lockfile runs only). */
+    overrides?: import('../modules/overrides').OverrideReport;
 }
 export interface Phase0Result {
     workspace: WorkspaceInfo;

package/dist/utils/translator-caller.js

@@ -92,7 +92,7 @@ async function callTranslator(entries, sourceLang, targetLang, byokConfig, brand
     if (needsFallback) {
         logger_1.engineLogger.warn('Rust translator returned untargeted translations or unavailable, falling back to HF Inference API');
         try {
-            const hfResults = await callHuggingFaceNLLB(entries, sourceLang, targetLang);
+            const hfResults = await callHuggingFaceNLLB(entries, sourceLang, targetLang, outerSignal);
             if (hfResults.translations.length > 0) {
                 return { translations: hfResults.translations, metadata: { ...rustResult?.metadata, fallback: 'hf-inference-api' } };
             }
@@ -137,12 +137,15 @@ async function callByokTranslator(entries, sourceLang, targetLang, byokConfig, b
     }
     return { translations, metadata: result.metadata };
 }
-async function callHuggingFaceNLLB(entries, sourceLang, targetLang) {
+async function callHuggingFaceNLLB(entries, sourceLang, targetLang, 
+/** The caller gave up (time budget, client gone): stop instead of finishing every entry. */
+outerSignal) {
     const hfToken = process.env.HF_TOKEN || process.env.HF_API_TOKEN;
     const model = 'facebook/nllb-200-distilled-600M';
     const baseUrl = `https://api-inference.huggingface.co/models/${model}`;
     const translations = [];
     for (const entry of entries) {
+        outerSignal?.throwIfAborted();
         const response = await fetch(baseUrl, {
             method: 'POST',
             headers: {
@@ -153,7 +156,7 @@ async function callHuggingFaceNLLB(entries, sourceLang, targetLang) {
                 inputs: entry.value,
                 parameters: { src_lang: sourceLang, tgt_lang: targetLang },
             }),
-            signal: AbortSignal.timeout(60000),
+            signal: outerSignal ? AbortSignal.any([AbortSignal.timeout(60000), outerSignal]) : AbortSignal.timeout(60000),
         });
         if (!response.ok) {
             const body = await response.text().catch(() => '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babelize/engine",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Babelize translation pipeline (extract, keygen, translate, inject). Infrastructure is injected through provider/store interfaces.",
   "keywords": [
     "babelize",