@babelize/engine 0.2.0 → 0.3.0

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.0",
+  "version": "0.3.0",
   "description": "Babelize translation pipeline (extract, keygen, translate, inject). Infrastructure is injected through provider/store interfaces.",
   "keywords": [
     "babelize",