@babelize/engine 0.0.0-stage → 0.1.0

package/dist/orchestrator.js

@@ -0,0 +1,616 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEngineV2 = runEngineV2;
+const fs = __importStar(require("fs-extra"));
+const logger_1 = require("./utils/logger");
+const types_1 = require("@babelize/types");
+const workspace_1 = require("./modules/workspace");
+const workspace_2 = require("./utils/workspace");
+const extract_1 = require("./modules/extractor/extract");
+const keygen_1 = require("./modules/keygen");
+const locale_builder_1 = require("./modules/locale-builder");
+const translate_1 = require("./modules/translator/translate");
+const translator_caller_1 = require("./utils/translator-caller");
+const injection_1 = require("./modules/injection");
+const summary_1 = require("./modules/summary");
+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 not_injected_1 = require("./utils/not-injected");
+const language_codes_1 = require("./modules/translator/language-codes");
+const format_injection_1 = require("./modules/format-injection");
+const extraction_options_1 = require("./utils/extraction-options");
+/**
+ * Whether the run's translator is an LLM (BYOK or an injected provider). The
+ * NLLB service can't translate ICU plural messages. `capabilities.icu`
+ * overrides the guess.
+ */
+function llmTranslator(config) {
+    return config.capabilities?.icu ?? (!!config.byok || !!config.providers?.translator);
+}
+/**
+ * Engine v2 Orchestrator (backend runtime)
+ *
+ * This is the single, clean wiring layer for the pipeline.
+ * Workers/controllers call `runEngineV2()`.
+ */
+async function runEngineV2(config) {
+    if (config.logger) {
+        const { logger, ...rest } = config;
+        return (0, logger_1.runWithEngineLogger)(logger, () => runEngineV2(rest));
+    }
+    const startTime = Date.now();
+    try {
+        logger_1.engineLogger.info('Starting Babelize engine v2 pipeline', {
+            workspacePath: config.workspacePath,
+            targetLocales: config.targetLocales,
+            dryRun: config.dryRun,
+        });
+        // The file-list cache is per run: a long-lived worker (or a CLI rerun in
+        // the same process) must see files added since the previous run.
+        (0, file_utils_1.clearFindFilesCache)();
+        config.onProgress?.('Validating workspace...', 'validation', 'running');
+        const { workspace } = await (0, workspace_1.validateWorkspace)(config);
+        const frameworkConfig = types_1.FRAMEWORK_CONFIGS[workspace.framework] || types_1.FRAMEWORK_CONFIGS['unknown'];
+        config.targetLocales = config.targetLocales.filter((l) => l !== config.sourceLocale);
+        // Remove stale locale files from previous runs that are no longer in targetLocales.
+        // git reset --hard only resets tracked files; generated locale files are untracked
+        // and persist across runs, causing stale languages to appear in outputs.
+        await (0, workspace_2.removeStaleLocales)(config.workspacePath, config.targetLocales, config.sourceLocale, workspace.localeFormat, workspace.publicDir);
+        config.onProgress?.('Extracting strings from codebase...', 'extraction', 'running');
+        // One resolved ICU decision for extraction, translation and injection (#248).
+        const icuOptions = await (0, extraction_options_1.resolveIcuOptions)(workspace, llmTranslator(config));
+        if (!icuOptions.sentences) {
+            logger_1.engineLogger.warn('i18next-icu not loaded by the project i18n config; keeping JSX sentences as fragments');
+        }
+        const { extraction } = await (0, extract_1.extractStrings)(workspace, config.filesToProcess, icuOptions);
+        if (extraction.warnings && extraction.warnings.length > 0) {
+            logger_1.engineLogger.warn('Extraction warnings', { count: extraction.warnings.length, warnings: extraction.warnings });
+        }
+        if (extraction.skippedFiles && extraction.skippedFiles.length > 0) {
+            logger_1.engineLogger.warn('Files skipped during extraction', {
+                count: extraction.skippedFiles.length,
+                files: extraction.skippedFiles.map((f) => `${f.file}: ${f.reason}${f.details ? ' — ' + f.details : ''}`),
+            });
+        }
+        // Partition format strings (currency/date/number) from translatable strings.
+        // Gate on format-inject phase being in the framework's phases AND formatConfig being enabled (D5).
+        // This means static HTML gets format strings as translatable (month names, currency as text)
+        // instead of silently dropping them.
+        const formatPartitionEnabled = frameworkConfig.phases.includes('format-inject') && config.formatConfig?.enabled;
+        const [translatableStrings, formatStrings] = formatPartitionEnabled
+            ? (0, format_injection_1.partitionFormatStrings)(extraction.strings)
+            : [extraction.strings, []];
+        const existingLocale = await (0, locale_builder_1.readLocaleFile)(workspace, config.sourceLocale);
+        const existingData = existingLocale || {};
+        // Strings injected by earlier runs are no longer extracted, but their keys
+        // are still in the source locale file. With a lockfile those keys must
+        // still be carried into every target locale (and translated for newly
+        // added locales), so "nothing new to extract" is not "nothing to do".
+        const hasExistingKeys = !!config.projectId && Object.keys(sourceLocaleKeys(existingData)).length > 0;
+        if (translatableStrings.length === 0 && formatStrings.length === 0 && !hasExistingKeys) {
+            logger_1.engineLogger.info('No strings found, finishing early');
+            return createEmptyResult(startTime, extraction.warnings, extraction.skippedFiles, extraction.notInjected);
+        }
+        // Use only translatable strings for the rest of the pipeline
+        config.onProgress?.('Generating translation keys...', 'keygen', 'running');
+        const { keyGeneration } = (0, keygen_1.generateKeys)(translatableStrings, existingData);
+        // ── Lockfile: partition keys ─────────────────────────────
+        let lockfileStats = { reused: 0, translated: 0, changed: 0 };
+        let tmHits = 0;
+        // (key, locale) translations the translator produced this run — the
+        // billable work. Lockfile/TM/cache reuse and failures are excluded.
+        let translatedThisRun = 0;
+        let keyUsage;
+        let translationMetadata = {};
+        if (config.projectId) {
+            config.onProgress?.('Checking lockfile for cached translations...', 'lockfile', 'running');
+            // Force re-translate: clear lockfile first
+            if (config.forceTranslation) {
+                await (0, lockfile_1.clearLockfile)(config.projectId, config.dataDir);
+                logger_1.engineLogger.info('Force translation: cleared lockfile', { projectId: config.projectId });
+            }
+            let lockfile = await (0, lockfile_1.loadLockfile)(config.projectId, config.dataDir);
+            config.onProgress?.('Processing source locale file...', 'locale', 'running');
+            const { localeHandling } = await (0, locale_builder_1.handleBaseLocale)(workspace, keyGeneration.keys, config.sourceLocale, config.dryRun);
+            // Build flat key→value map for partitioning: every key in the source
+            // locale, not just the ones extracted this run. Keys injected by earlier
+            // runs aren't re-extracted, and partitioning only this run's keys used to
+            // drop their translations from every target file (and left newly added
+            // locales with nothing to translate).
+            const flatKeys = sourceLocaleKeys(localeHandling.sourceLocale.data);
+            const contextMap = {};
+            const extractionContextMap = {};
+            for (const k of keyGeneration.keys) {
+                flatKeys[k.key] = k.value;
+                if (k.parentContext) {
+                    contextMap[k.key] = k.parentContext;
+                }
+                if (k.extractionContext) {
+                    extractionContextMap[k.key] = k.extractionContext;
+                }
+            }
+            // Advisory only: which source keys no code seems to reference. The scan
+            // is a heuristic (renamed translators, other file types, templates), so
+            // it never changes what is translated, kept or written.
+            keyUsage = await (0, key_usage_1.reportKeyUsage)(workspace, flatKeys, new Set(keyGeneration.keys.map((k) => k.key)));
+            // Pseudo-localization (--provider pseudo) is not a translation: a real
+            // run treats pseudo values in the lockfile as missing and translates them.
+            const lockfileRead = { pseudo: config.providers?.translator?.pseudo === true };
+            const partition = (0, lockfile_1.partitionKeys)(lockfile, flatKeys, config.targetLocales, lockfileRead);
+            lockfileStats = (0, lockfile_1.computeLockfileStats)(partition);
+            logger_1.engineLogger.info('Lockfile partition result', {
+                unchanged: partition.unchanged.length,
+                newKeys: partition.newKeys.length,
+                changed: partition.changed.length,
+                missingLocales: partition.missingLocales.length,
+            });
+            // Collect cached translations for unchanged keys, and for keys that only
+            // 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);
+            config.onProgress?.('Translating to target locales...', 'translation', 'running');
+            const translatorHealthy = await isTranslatorHealthy(config);
+            if (!translatorHealthy) {
+                const msg = 'Translator service is not responding — only source locale (en.json) was generated. Target locale files will be missing. Please ensure the translator service is running and try again.';
+                logger_1.engineLogger.warn(msg);
+                config.onProgress?.(msg, 'translation', 'warning');
+            }
+            // Only translate keys that need it (new + changed + missing locales)
+            const keysNeedingTranslation = [
+                ...partition.newKeys,
+                ...partition.changed,
+                ...partition.missingLocales,
+            ];
+            let translation;
+            if (keysNeedingTranslation.length === 0) {
+                logger_1.engineLogger.info('All keys reused from lockfile, skipping translation');
+                translation = { locales: [], errors: [], failures: [] };
+            }
+            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 });
+                translation = result.translation;
+                tmHits = result.stats.tmHits;
+                translationMetadata = result.metadata;
+                translatedThisRun = freshTranslations(translation, translationMetadata);
+                assertSomethingTranslated(translation);
+            }
+            else {
+                const errorMsg = 'Translator service unavailable — target locale files (hi.json, fr.json, etc.) were NOT generated. Only source locale (en.json) was created. Check that TRANSLATOR_URL or BYOK provider is configured and the service is running.';
+                logger_1.engineLogger.error(errorMsg);
+                config.onProgress?.(errorMsg, 'translation', 'error');
+                throw new Error(errorMsg);
+            }
+            // Merge cached translations into translation output locale data
+            for (const locale of translation.locales) {
+                const cached = cachedTranslations[locale.locale];
+                if (cached) {
+                    const existingFlat = (0, keygen_1.flattenLocaleData)(locale.data);
+                    const merged = { ...cached, ...existingFlat };
+                    // Rebuild the locale data with cached + new
+                    for (const [k, v] of Object.entries(merged)) {
+                        setNestedKey(locale.data, k, v);
+                    }
+                }
+            }
+            // Also create locale files for locales that were fully cached (no translator call)
+            for (const targetLocale of config.targetLocales) {
+                const existsInTranslation = translation.locales.some((l) => l.locale === targetLocale);
+                if (!existsInTranslation && cachedTranslations[targetLocale] && Object.keys(cachedTranslations[targetLocale]).length > 0) {
+                    // Filter out cached translations that are identical to source text
+                    // (identity translations mean the previous run's translator was unavailable)
+                    // A locale where *every* cached value equals the source is what an
+                    // unavailable translator used to leave behind: skip it. Otherwise
+                    // keep all values — names and codes are legitimately identical, and
+                    // dropping them would delete real translations.
+                    const realTranslations = { ...cachedTranslations[targetLocale] };
+                    const hasRealTranslations = Object.entries(realTranslations).some(([k, v]) => flatKeys[k] !== v);
+                    if (!hasRealTranslations) {
+                        logger_1.engineLogger.warn(`Skipping cached locale "${targetLocale}" — all cached entries are identity translations (same as source). Translator may be unavailable.`);
+                        continue;
+                    }
+                    const cachedData = {};
+                    for (const [k, v] of Object.entries(realTranslations)) {
+                        setNestedKey(cachedData, k, v);
+                    }
+                    const localePath = (0, file_utils_1.localeFilePath)(workspace.path, workspace.publicDir, workspace.localeFormat, targetLocale);
+                    translation.locales.push({
+                        locale: targetLocale,
+                        path: localePath.relativeFile,
+                        data: cachedData,
+                        isNew: false,
+                    });
+                }
+            }
+            // Locales rebuilt from the lockfile carry no _meta block; give them the
+            // same one a freshly translated locale gets.
+            for (const locale of translation.locales) {
+                if (!locale.data._meta) {
+                    locale.data._meta = { dir: (0, language_codes_1.isRTL)(locale.locale) ? 'rtl' : 'ltr', language: locale.locale };
+                }
+            }
+            // ── Lockfile: update after translation ─────────────────
+            config.onProgress?.('Updating lockfile...', 'lockfile', 'running');
+            const allTranslatedPerLocale = {};
+            for (const locale of translation.locales) {
+                allTranslatedPerLocale[locale.locale] = (0, keygen_1.flattenLocaleData)(locale.data);
+            }
+            // Only persist lockfile if we actually generated translation data,
+            // to prevent corrupting the lockfile when the translator was unavailable.
+            const hasRealTranslations = translation.locales.length > 0;
+            if (hasRealTranslations) {
+                // Lockfile-reused keys skip the translator, so they would otherwise
+                // never reach TM. Backfill them without overwriting existing entries —
+                // once: keys already marked inTm in the lockfile are skipped, so an
+                // unchanged project doesn't re-upsert every key on every run.
+                const lockfileMetadata = { ...translationMetadata };
+                if (lockfileRead.pseudo) {
+                    // Record what this run produced as pseudo, so a later real run replaces it.
+                    for (const [locale, keys] of Object.entries(translationMetadata)) {
+                        lockfileMetadata[locale] = Object.fromEntries(Object.entries(keys).map(([k, m]) => [k, { ...(m ?? {}), pseudo: true }]));
+                    }
+                }
+                if (!config.dryRun) {
+                    const pending = {};
+                    for (const [locale, keys] of Object.entries(cachedTranslations)) {
+                        for (const [key, value] of Object.entries(keys)) {
+                            if (lockfile.keys[key]?.metadata?.[locale]?.inTm)
+                                continue;
+                            (pending[locale] ?? (pending[locale] = {}))[key] = value;
+                        }
+                    }
+                    try {
+                        const settled = await (0, translate_1.backfillTranslationMemory)(config.projectId, config.sourceLocale, flatKeys, pending, new Set(Object.keys(contextMap)), config.providers);
+                        for (const [locale, keys] of Object.entries(settled)) {
+                            const forLocale = (lockfileMetadata[locale] = { ...(lockfileMetadata[locale] ?? {}) });
+                            for (const key of keys) {
+                                forLocale[key] = { ...(lockfile.keys[key]?.metadata?.[locale] ?? {}), ...(forLocale[key] ?? {}), inTm: true };
+                            }
+                        }
+                    }
+                    catch (err) {
+                        logger_1.engineLogger.error('TM backfill from lockfile failed', {
+                            projectId: config.projectId,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+                const previousLockfile = lockfile;
+                lockfile = (0, lockfile_1.updateLockfile)(lockfile, flatKeys, allTranslatedPerLocale, config.projectId, lockfileMetadata);
+                lockfile = (0, lockfile_1.dropFailedTranslations)(lockfile, translation.failures ?? []);
+                // 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));
+                // Users commit the lockfile: an unchanged one is not rewritten (no
+                // new timestamp, no diff).
+                const lockfileOnDisk = await fs.pathExists((0, lockfile_1.getLockfilePath)(config.projectId, config.dataDir));
+                if (!config.dryRun && (!lockfileOnDisk || (0, lockfile_1.lockfileChanged)(previousLockfile, lockfile))) {
+                    await (0, lockfile_1.saveLockfile)(config.projectId, lockfile, config.dataDir);
+                }
+            }
+            else {
+                logger_1.engineLogger.warn('Skipping lockfile update: no translation data generated (translator may be unavailable)', {
+                    projectId: config.projectId,
+                });
+            }
+            const result = await finalizePipeline({
+                extraction, keyGeneration, localeHandling, translation,
+                config, startTime, workspace, allTranslatedPerLocale,
+                lockfileStats, tmHits, translationMetadata,
+                translatedThisRun, keyUsage,
+                formatStrings, frameworkConfig,
+            });
+            return result;
+        }
+        // ── No projectId: run without lockfile (legacy path) ─────
+        const contextMap = {};
+        const extractionContextMap = {};
+        for (const k of keyGeneration.keys) {
+            if (k.parentContext) {
+                contextMap[k.key] = k.parentContext;
+            }
+            if (k.extractionContext) {
+                extractionContextMap[k.key] = k.extractionContext;
+            }
+        }
+        config.onProgress?.('Processing source locale file...', 'locale', 'running');
+        const { localeHandling } = await (0, locale_builder_1.handleBaseLocale)(workspace, keyGeneration.keys, config.sourceLocale, config.dryRun);
+        config.onProgress?.('Translating to target locales...', 'translation', 'running');
+        const translatorHealthy = await isTranslatorHealthy(config);
+        if (!translatorHealthy) {
+            const msg = 'Translator service is not responding — only source locale (en.json) was generated. Target locale files will be missing. Please ensure the translator service is running and try again.';
+            logger_1.engineLogger.warn(msg);
+            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 })
+            : {
+                translation: {
+                    locales: [],
+                    errors: config.targetLocales.map((l) => ({ locale: l, error: 'Translator service unavailable — target locale files were not generated. Only the source locale file was created.' })),
+                },
+                stats: { tmHits: 0 },
+                metadata: {}
+            };
+        const translation = translationResult.translation;
+        tmHits = translationResult.stats.tmHits;
+        translationMetadata = translationResult.metadata;
+        translatedThisRun = freshTranslations(translation, translationMetadata);
+        assertSomethingTranslated(translation);
+        // Fail immediately when translation errors occurred — before injection/finalization
+        if (translation.errors && translation.errors.length > 0) {
+            const errorMsg = translation.errors.map((e) => `${e.locale}: ${e.error}`).join('; ');
+            logger_1.engineLogger.error('Translation failed', { errors: errorMsg });
+            throw new Error(`Translation failed: ${errorMsg}`);
+        }
+        const allTranslatedPerLocale = {};
+        for (const locale of translation.locales) {
+            allTranslatedPerLocale[locale.locale] = (0, keygen_1.flattenLocaleData)(locale.data);
+        }
+        const result = await finalizePipeline({
+            extraction, keyGeneration, localeHandling, translation,
+            config, startTime, workspace, allTranslatedPerLocale,
+            lockfileStats: undefined, tmHits, translationMetadata,
+            translatedThisRun, keyUsage,
+            formatStrings, frameworkConfig,
+        });
+        return result;
+    }
+    catch (error) {
+        logger_1.engineLogger.error('Engine v2 error', { error: error?.message ?? String(error) });
+        return {
+            success: false,
+            error: error?.message ?? String(error),
+            stats: {
+                filesScanned: 0,
+                filesWithStrings: 0,
+                stringsExtracted: 0,
+                keysGenerated: 0,
+                filesModified: 0,
+                injectionsApplied: 0,
+                localeFilesCreated: 0,
+                processingTimeMs: Date.now() - startTime,
+            },
+            locales: [],
+            injections: { modifiedFiles: [], skippedFiles: [], totalInjections: 0 },
+            warnings: [],
+            skipped: [],
+            diffs: [],
+        };
+    }
+}
+/**
+ * (key, locale) translations the translator produced this run, in locales
+ * that made it into the output: the billable work. Values reused from
+ * translation memory or the cache, and source text copied through untouched
+ * (placeholders, codes), are not counted; failed keys are not in the output.
+ */
+function fallbackTranslations(metadata) {
+    const out = [];
+    for (const [locale, keys] of Object.entries(metadata ?? {})) {
+        for (const [key, m] of Object.entries(keys ?? {}))
+            if (m?.fallback)
+                out.push({ key, locale });
+    }
+    return out;
+}
+function freshTranslations(translation, metadata) {
+    let n = 0;
+    for (const locale of translation.locales) {
+        const meta = metadata[locale.locale] ?? {};
+        for (const [key, value] of Object.entries((0, keygen_1.flattenLocaleData)(locale.data))) {
+            if (key === '_meta' || key.startsWith('_meta.') || !value)
+                continue;
+            const m = meta[key];
+            // Backup-translator output isn't billed: the next run redoes it with the AI translator.
+            if (m?.fromMemory || m?.fromCache || m?.passthrough || m?.fallback)
+                continue;
+            n++;
+        }
+    }
+    return n;
+}
+/** Flat key → source text for a source locale file, without the `_meta` block. */
+function sourceLocaleKeys(data) {
+    const flat = {};
+    for (const [key, value] of Object.entries((0, keygen_1.flattenLocaleData)(data))) {
+        if (key === '_meta' || key.startsWith('_meta.'))
+            continue;
+        flat[key] = value;
+    }
+    return flat;
+}
+/**
+ * An injected TranslationProvider is the host's responsibility (it reports
+ * per-key failures itself), so only probe the built-in translator/BYOK
+ * endpoint when the engine is going to use it.
+ */
+async function isTranslatorHealthy(config) {
+    if (config.providers?.translator)
+        return true;
+    return (0, translator_caller_1.checkTranslatorHealth)(config.byok);
+}
+function createEmptyResult(startTime, warnings = [], skipped = [], notInjected = []) {
+    return {
+        success: true,
+        notInjected,
+        stats: {
+            filesScanned: 0,
+            filesWithStrings: 0,
+            stringsExtracted: 0,
+            keysGenerated: 0,
+            filesModified: 0,
+            injectionsApplied: 0,
+            localeFilesCreated: 0,
+            processingTimeMs: Date.now() - startTime,
+        },
+        locales: [],
+        injections: { modifiedFiles: [], skippedFiles: [], totalInjections: 0 },
+        warnings,
+        skipped,
+        diffs: [],
+    };
+}
+/**
+ * Set a value in a nested object using a dot-separated key path.
+ * e.g. setNestedKey(obj, 'homepage.hero.title', 'Hello') →
+ *   { homepage: { hero: { title: 'Hello' } } }
+ */
+function setNestedKey(obj, dottedKey, value) {
+    const parts = dottedKey.split('.');
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (!(part in current)) {
+            current[part] = {};
+        }
+        else if (typeof current[part] === 'string') {
+            logger_1.engineLogger.warn('Overwriting string value with object for nested key', {
+                key: dottedKey,
+                part,
+            });
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+/**
+ * A run where translation was needed but no string in any locale could be
+ * translated is a failed run, not an empty success: fail it with the reasons
+ * so the job errors (and is not billed) instead of reporting success.
+ */
+function assertSomethingTranslated(translation) {
+    const failures = translation.failures ?? [];
+    if (failures.length === 0 || translation.locales.length > 0)
+        return;
+    const byReason = new Map();
+    for (const f of failures)
+        byReason.set(f.reason, (byReason.get(f.reason) ?? 0) + 1);
+    const summary = [...byReason].map(([reason, n]) => `${n} ${reason}`).join(', ');
+    const sample = failures.find((f) => f.message)?.message;
+    throw new Error(`No strings could be translated (${summary})${sample ? `: ${sample}` : ''}`);
+}
+async function finalizePipeline(params) {
+    const { extraction, keyGeneration, localeHandling, translation, config, startTime, workspace, allTranslatedPerLocale, lockfileStats, tmHits, translationMetadata, formatStrings, frameworkConfig, translatedThisRun, keyUsage, } = params;
+    const keyMapping = (0, keygen_1.createKeyMapping)(keyGeneration.keys);
+    // Injection: AST-based i18n hook injection (skipped for frameworks like Django)
+    let injection;
+    if (frameworkConfig.phases.includes('inject')) {
+        config.onProgress?.('Injecting translations into code...', 'injection', 'running');
+        // Inject exactly the nodes extraction selected (by source offset).
+        const positions = new Map();
+        for (const str of extraction.strings)
+            if (str.offsets)
+                positions.set(str.id, new Set(str.offsets));
+        injection = await (0, injection_1.injectTranslations)(workspace, keyMapping, config.confidenceThreshold, config.dryRun, positions);
+    }
+    else {
+        injection = { modifiedFiles: [], skippedFiles: [], totalInjections: 0 };
+    }
+    const notInjected = frameworkConfig.phases.includes('inject')
+        ? [...(0, not_injected_1.findNotInjected)(keyGeneration, injection), ...(extraction.notInjected ?? [])]
+        : [];
+    if (notInjected.length > 0) {
+        logger_1.engineLogger.warn('Extracted strings not wired into code', { count: notInjected.length });
+    }
+    // Format injection: replace hardcoded dates/currencies with Intl.* API calls
+    if (frameworkConfig.phases.includes('format-inject') && config.formatConfig?.enabled && formatStrings && formatStrings.length > 0) {
+        config.onProgress?.('Injecting Intl.* format replacements...', 'injection', 'running');
+        const formatInjection = await (0, format_injection_1.injectFormats)(workspace, formatStrings, config.formatConfig, config.dryRun);
+        if (formatInjection.totalInjections > 0) {
+            injection.modifiedFiles.push(...formatInjection.modifiedFiles);
+            injection.totalInjections += formatInjection.totalInjections;
+            injection.skippedFiles.push(...formatInjection.skippedFiles);
+        }
+        logger_1.engineLogger.info('Format injection complete', {
+            totalInjections: formatInjection.totalInjections,
+        });
+    }
+    // Finalization: install i18n deps, create config files, modify entry points
+    const finalizationNotes = [];
+    if (frameworkConfig.phases.includes('finalize')) {
+        config.onProgress?.('Finalizing project...', 'finalization', 'running');
+        const { finalization } = await (0, finalization_1.finalizeProject)(workspace, config.dryRun, {
+            targetLocales: config.targetLocales,
+            sourceLocale: config.sourceLocale,
+            installDependencies: config.installDependencies,
+        });
+        finalizationNotes.push(...(finalization.warnings ?? []));
+        if (finalization.dependenciesInvalid) {
+            if (finalization.packagesInstalled) {
+                logger_1.engineLogger.info('New dependencies installed successfully');
+            }
+            else {
+                logger_1.engineLogger.warn(finalization.warnings?.find((w) => w.includes('auto-install')) || 'New dependencies added. Please run your package manager install.');
+            }
+        }
+        if (finalization.configFileCreated) {
+            logger_1.engineLogger.info('Created i18n configuration file');
+        }
+        if (finalization.entryPointModified) {
+            logger_1.engineLogger.info('Injected i18n import into entry point');
+        }
+    }
+    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);
+    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];
+    config.onProgress?.('Complete', 'complete', 'success');
+    const allSkipped = [...extraction.skippedFiles, ...injection.skippedFiles];
+    return {
+        success: true,
+        translationFailures: translation.failures ?? [],
+        stats,
+        locales: allLocales,
+        injections: injection,
+        warnings: [...warnings],
+        skipped: allSkipped,
+        diffs,
+        notes: finalizationNotes,
+        keyUsage,
+        notInjected,
+        results: {
+            source: (0, keygen_1.flattenLocaleData)(localeHandling.sourceLocale.data),
+            targets: allTranslatedPerLocale,
+            metadata: translationMetadata,
+        },
+    };
+}

package/dist/providers/default-translation-provider.d.ts

@@ -0,0 +1,20 @@
+import type { ByokProvider } from '@babelize/types';
+import type { KeyResult, TranslationProvider } from './types';
+/**
+ * The translator the engine has always used: the Babelize translator service
+ * (TRANSLATOR_URL, with failover), or the customer's own LLM key (BYOK).
+ * Adapts its batch response to one KeyResult per requested key.
+ */
+export declare function createDefaultTranslationProvider(byokConfig?: {
+    provider: ByokProvider;
+    apiKey: string;
+    model?: string;
+}): TranslationProvider;
+/** One result per requested key, in request order; extra keys in the response are ignored. */
+export declare function toKeyResults(requestedKeys: string[], translations: Array<{
+    key: string;
+    value: string;
+    confidence?: number;
+    engine?: string;
+    warnings?: string[];
+}>): KeyResult[];

package/dist/providers/default-translation-provider.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultTranslationProvider = createDefaultTranslationProvider;
+exports.toKeyResults = toKeyResults;
+const translator_caller_1 = require("../utils/translator-caller");
+/**
+ * The translator the engine has always used: the Babelize translator service
+ * (TRANSLATOR_URL, with failover), or the customer's own LLM key (BYOK).
+ * Adapts its batch response to one KeyResult per requested key.
+ */
+function createDefaultTranslationProvider(byokConfig) {
+    return {
+        async translateBatch({ entries, sourceLang, targetLang, brandVoice, targetLocale, glossary, hints }, options = {}) {
+            const { translations } = await (0, translator_caller_1.callTranslator)(entries, sourceLang, targetLang, byokConfig, brandVoice, { targetLocale, glossary, hints, signal: options.signal });
+            return toKeyResults(entries.map((e) => e.key), translations ?? []);
+        },
+    };
+}
+/** One result per requested key, in request order; extra keys in the response are ignored. */
+function toKeyResults(requestedKeys, translations) {
+    const byKey = new Map(translations.map((t) => [t.key, t]));
+    return requestedKeys.map((key) => {
+        const t = byKey.get(key);
+        if (!t)
+            return { key, status: 'failed', reason: 'missing_from_response', retryable: true };
+        if (!t.value)
+            return { key, status: 'failed', reason: 'empty_value', retryable: true };
+        return { key, status: 'ok', value: t.value, confidence: t.confidence, engine: t.engine, warnings: t.warnings };
+    });
+}