@babelize/engine 0.0.0-stage → 0.1.0

package/dist/local/report.js

@@ -0,0 +1,186 @@
+"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.BABELIZE_GITIGNORE = exports.DEFAULT_REPORT_FILE = exports.TRANSLATE_REPORT_SCHEMA_ID = exports.TRANSLATE_REPORT_SCHEMA_VERSION = void 0;
+exports.buildTranslateReport = buildTranslateReport;
+exports.writeTranslateReport = writeTranslateReport;
+exports.ensureReportGitignored = ensureReportGitignored;
+const promises_1 = require("node:fs/promises");
+const path = __importStar(require("node:path"));
+/**
+ * The QA report of a local translate run: what `babelize translate --json`
+ * prints and what it writes to `.babelize/local/report.json`. One schema for
+ * both, described by `schemas/translate-report.schema.json` in this package.
+ * Every per-key list is complete (no caps), unlike the MCP tool's response.
+ */
+exports.TRANSLATE_REPORT_SCHEMA_VERSION = 1;
+exports.TRANSLATE_REPORT_SCHEMA_ID = 'https://babelize.co/schemas/translate-report.v1.json';
+/** Default report location, relative to the project root. */
+exports.DEFAULT_REPORT_FILE = '.babelize/local/report.json';
+/** Keeps the report out of git while the lockfile next to it stays committed. */
+exports.BABELIZE_GITIGNORE = '.babelize/.gitignore';
+const GITIGNORE_ENTRY = 'local/report.json';
+/** The report of a finished run (`r` from runLocalTranslate). */
+function buildTranslateReport(r) {
+    const failures = r.translationFailures.map((f) => ({
+        locale: f.locale,
+        key: f.key,
+        source: f.source,
+        reason: f.reason,
+        retryable: f.retryable,
+        ...(f.message ? { message: f.message } : {}),
+    }));
+    const failedBy = new Map(failures.map((f) => [`${f.locale}\0${f.key}`, f]));
+    const qaItems = r.locales.flatMap((l) => l.qa.map((q) => ({ locale: l.locale, key: q.key, warnings: q.warnings })));
+    const qaBy = new Map(qaItems.map((q) => [`${q.locale}\0${q.key}`, q.warnings]));
+    const missing = r.locales.flatMap((l) => l.missing.filter((k) => !failedBy.has(`${l.locale}\0${k}`)).map((key) => ({ locale: l.locale, key })));
+    const unchanged = r.locales.flatMap((l) => l.sameAsSource.map((key) => ({ locale: l.locale, key, value: r.results.targets[l.locale]?.[key] ?? '' })));
+    const unchangedBy = new Set(unchanged.map((u) => `${u.locale}\0${u.key}`));
+    const keys = Object.entries(r.results.source).map(([key, source]) => {
+        const locales = {};
+        for (const l of r.locales) {
+            const id = `${l.locale}\0${key}`;
+            const value = r.results.targets[l.locale]?.[key];
+            const failed = failedBy.get(id);
+            const warnings = qaBy.get(id);
+            let entry;
+            if (failed) {
+                entry = { status: 'failed', reason: failed.reason, retryable: failed.retryable, ...(failed.message ? { message: failed.message } : {}) };
+                // A failed re-translation keeps the earlier value on disk.
+                if (value)
+                    entry.value = value;
+            }
+            else if (value === undefined || value === '')
+                entry = { status: 'missing' };
+            else if (warnings)
+                entry = { status: 'warning', value, warnings };
+            else if (unchangedBy.has(id))
+                entry = { status: 'unchanged', value };
+            else
+                entry = { status: 'translated', value };
+            locales[l.locale] = entry;
+        }
+        return { key, source, locales };
+    });
+    const translations = r.locales.reduce((n, l) => n + l.translated, 0);
+    const newTranslations = Math.min(r.stats.translatedThisRun ?? r.stats.keysSentToTranslator, translations);
+    const started = Number.isFinite(r.startedAt) ? r.startedAt : Date.now() - r.durationMs;
+    return {
+        $schema: exports.TRANSLATE_REPORT_SCHEMA_ID,
+        schemaVersion: exports.TRANSLATE_REPORT_SCHEMA_VERSION,
+        ok: failures.length === 0,
+        startedAt: new Date(started).toISOString(),
+        finishedAt: new Date(started + r.durationMs).toISOString(),
+        durationMs: r.durationMs,
+        framework: r.framework,
+        frameworkStatus: r.frameworkStatus,
+        provider: r.provider ? { provider: r.provider.provider, name: r.provider.name, ...(r.provider.model ? { model: r.provider.model } : {}) } : null,
+        sourceLocale: r.sourceLocale,
+        targetLocales: r.targetLocales,
+        keptLocales: r.keptLocales,
+        droppedLocales: r.droppedLocales,
+        dryRun: r.dryRun,
+        applied: r.applied,
+        filesChanged: { added: r.changes.added, modified: r.changes.modified, deleted: r.changes.deleted },
+        diffSummary: r.diffStat,
+        ...(r.diff !== undefined ? { diff: r.diff } : {}),
+        stats: r.stats,
+        summary: {
+            sourceKeys: Object.keys(r.results.source).length,
+            translations,
+            newTranslations,
+            reused: Math.max(0, translations - newTranslations),
+            failed: failures.length,
+            qaWarnings: qaItems.length,
+            missing: missing.length,
+            unchanged: unchanged.length,
+            notInjected: r.notInjected.length,
+        },
+        locales: r.locales.map((l) => {
+            const failed = l.failed.length;
+            const otherMissing = l.missing.filter((k) => !failedBy.has(`${l.locale}\0${k}`)).length;
+            return {
+                locale: l.locale,
+                status: failed > 0 ? 'failed' : l.qa.length > 0 || otherMissing > 0 ? 'warning' : 'ok',
+                total: l.total,
+                translated: l.translated,
+                missing: l.missing.length,
+                failed,
+                qaWarnings: l.qa.length,
+                sameAsSource: l.sameAsSource.length,
+            };
+        }),
+        failures: { total: failures.length, items: failures },
+        qaWarnings: { total: qaItems.length, items: qaItems },
+        missing: { total: missing.length, items: missing },
+        unchanged: { total: unchanged.length, items: unchanged },
+        notInjected: { total: r.notInjected.length, items: r.notInjected },
+        unusedKeys: { total: r.unusedKeys.length, items: r.unusedKeys },
+        dynamicKeyFiles: r.dynamicKeyFiles,
+        keys,
+        warnings: r.warnings.map((w) => ({ type: w.type, file: w.file, ...(w.line !== undefined ? { line: w.line } : {}), message: w.message })),
+        notes: r.notes,
+        engineLog: r.engineLog,
+        ...(r.formatter ? { formatter: r.formatter } : {}),
+        lockfile: r.lockfile,
+        lockfileIgnored: r.lockfileIgnored,
+    };
+}
+/**
+ * Write the report as JSON. `file` is resolved against `projectDir`
+ * (default {@link DEFAULT_REPORT_FILE}); returns the absolute path written.
+ */
+async function writeTranslateReport(projectDir, report, file = exports.DEFAULT_REPORT_FILE) {
+    const abs = path.resolve(projectDir, file);
+    await (0, promises_1.mkdir)(path.dirname(abs), { recursive: true });
+    await (0, promises_1.writeFile)(abs, `${JSON.stringify(report, null, 2)}\n`);
+    return abs;
+}
+/**
+ * Make `.babelize/.gitignore` (in `root`) ignore the report, creating the
+ * file if needed. Returns true when it changed. The lockfile in the same
+ * folder stays committed.
+ */
+async function ensureReportGitignored(root) {
+    const file = path.join(root, exports.BABELIZE_GITIGNORE);
+    const current = await (0, promises_1.readFile)(file, 'utf8').catch(() => null);
+    if (current !== null && current.split(/\r?\n/).some((line) => line.trim().replace(/^\//, '') === GITIGNORE_ENTRY))
+        return false;
+    await (0, promises_1.mkdir)(path.dirname(file), { recursive: true });
+    const header = '# Babelize: the QA report of the last local run (the lockfile next to it is committed).\n';
+    const next = current === null ? `${header}${GITIGNORE_ENTRY}\n` : `${current.replace(/\n?$/, '\n')}${GITIGNORE_ENTRY}\n`;
+    await (0, promises_1.writeFile)(file, next);
+    return true;
+}

package/dist/local/translate-core.d.ts

@@ -0,0 +1,215 @@
+import type { EngineConfigV2, EngineResultV2 } from '../runtime/types';
+import type { TranslationFailure, TranslationProvider } from '../providers/types';
+import { type ByokProvider } from '@babelize/types';
+import type { HostedTranslationProvider } from './hosted-provider';
+import { type FormatResult } from './formatter';
+import { type FileDiffStat, type ApplyIo, type WorkspaceChanges } from './workspace-copy';
+/** Lockfile scope for local runs: `.babelize/local/babelize-lock.json` in the project root. */
+export declare const LOCAL_PROJECT_ID = "local";
+export declare const LOCAL_LOCKFILE = ".babelize/local/babelize-lock.json";
+export declare const SUPPORTED_LOCAL_FRAMEWORKS: readonly ["react", "nextjs"];
+export declare const BETA_LOCAL_FRAMEWORKS: readonly ["vue", "static"];
+export interface LocalTranslateOptions {
+    projectDir: string;
+    sourceLocale: string;
+    targetLocales: string[];
+    /** Compute and return the diff; write nothing to the project. */
+    dryRun: boolean;
+    /** Allow running on a dirty git tree. */
+    force: boolean;
+    /** The user's LLM key. Required unless `deps.translator` is injected. */
+    byok?: {
+        provider: ByokProvider;
+        apiKey: string;
+        model?: string;
+    };
+    /**
+     * Treat `targetLocales` as the complete list: locales translated earlier
+     * but not listed are removed. Default false: earlier locales are kept and
+     * brought up to date (from the lockfile, so only new strings cost tokens).
+     */
+    replace?: boolean;
+}
+export interface LocalTranslateDeps {
+    /** Replaces the BYOK translator (tests). */
+    translator?: TranslationProvider;
+    /**
+     * Babelize-hosted translation (BABELIZE_API_KEY). Used as the translator;
+     * its model is shown in the report and a bad key or empty balance stops
+     * the run with an actionable error.
+     */
+    hosted?: HostedTranslationProvider;
+    /** Engine entry point; injectable for tests. */
+    runEngine?: (config: EngineConfigV2) => Promise<EngineResultV2>;
+    /** Engine progress; `status` is running/success/warning/error. */
+    onProgress?: (message: string, phase?: string, status?: string) => void;
+    /** Called once the framework is known, before any LLM call. */
+    onFramework?: (framework: string, status: FrameworkStatus) => void;
+    /** Parent dir for the temp copy (defaults to the OS temp dir). */
+    tmpRoot?: string;
+    /** File operations for applying changes; injectable to simulate disk failures. */
+    applyIo?: ApplyIo;
+    /**
+     * How to name an injected `translator` in the report (e.g. the
+     * pseudo-localization provider). Without it the report has no provider.
+     */
+    translatorInfo?: {
+        provider: ReportProviderId;
+        name: string;
+        model?: string;
+    };
+}
+/** Provider ids a report can name: BYOK providers, Babelize-hosted, or pseudo-localization. */
+export type ReportProviderId = ByokProvider | 'babelize' | 'pseudo';
+export type FrameworkStatus = 'supported' | 'beta';
+export type LocalTranslateErrorCode = 'not_a_repo' | 'git_missing' | 'dirty' | 'invalid_locale' | 'no_translator' | 'unsupported_framework' | 'translator_unreachable'
+/** BABELIZE_API_KEY rejected. */
+ | 'hosted_auth'
+/** Babelize account out of AI credits. */
+ | 'hosted_credits' | 'engine_failed' | 'incomplete_translation'
+/** Writing to the project failed; see `changedFiles` for what is left changed. */
+ | 'apply_failed'
+/** Project files changed while the run was in progress; nothing was applied. */
+ | 'project_changed';
+export declare class LocalTranslateError extends Error {
+    readonly code: LocalTranslateErrorCode;
+    /** Files left changed in the project (only for a failed, un-rolled-back apply). */
+    readonly changedFiles: string[];
+    constructor(message: string, code: LocalTranslateErrorCode, 
+    /** Files left changed in the project (only for a failed, un-rolled-back apply). */
+    changedFiles?: string[]);
+}
+/** Per-locale outcome. `missing` and `sameAsSource` are what a reviewer should look at. */
+export interface LocaleReport {
+    locale: string;
+    /** Keys in the source locale. */
+    total: number;
+    /** Keys with a value (including values identical to the source, see `sameAsSource`). */
+    translated: number;
+    /** Keys with no value in this locale (the app will show the fallback). */
+    missing: string[];
+    /** Keys the engine could not translate this run, with the reason (subset of `missing`). */
+    failed: Array<{
+        key: string;
+        reason: string;
+        message?: string;
+        retryable: boolean;
+    }>;
+    /** Keys translated with QA warnings from the engine (glossary, length, …). */
+    qa: Array<{
+        key: string;
+        warnings: string[];
+    }>;
+    /**
+     * Keys whose value is identical to the source text. The engine already
+     * rejects untranslated output, so this is only a review hint (brand names,
+     * "OK", or a cached value from before that check existed).
+     */
+    sameAsSource: string[];
+}
+/**
+ * Everything a run produced. Structured so a per-key QA report (#237) can be
+ * rendered from it without re-running anything.
+ */
+export interface LocalTranslateReport {
+    framework: string;
+    frameworkStatus: FrameworkStatus;
+    /** `model` is absent for hosted runs where the server didn't report one. */
+    provider?: {
+        provider: ReportProviderId;
+        name: string;
+        model?: string;
+    };
+    sourceLocale: string;
+    /** Locales translated in this run: `--to` plus earlier locales (unless replace). */
+    targetLocales: string[];
+    /** Earlier locales that were kept and updated although not in `--to`. */
+    keptLocales: string[];
+    /** Earlier locales removed by `--replace` (files and lockfile entries). */
+    droppedLocales: string[];
+    /**
+     * Source keys with no t() reference found by a heuristic scan. Advisory
+     * only: they are still translated, kept and written like any other key.
+     */
+    unusedKeys: string[];
+    /** Strings extracted (and translated) but not wired into the code. */
+    notInjected: Array<{
+        file: string;
+        key: string;
+        text: string;
+        reason: string;
+    }>;
+    /** Files whose non-literal t() keys made every key count as used. */
+    dynamicKeyFiles: string[];
+    dryRun: boolean;
+    /** True when changes were written to the project. */
+    applied: boolean;
+    changes: WorkspaceChanges;
+    /** Unified diff of `changes` (always computed for --dry-run). */
+    diff?: string;
+    /** Lines added/removed per changed file, from old vs new content. */
+    diffStat: FileDiffStat[];
+    stats: {
+        filesScanned: number;
+        stringsExtracted: number;
+        keysExtracted: number;
+        injectionsApplied: number;
+        keysFromLockfile: number;
+        keysSentToTranslator: number;
+        /** (key, locale) translations produced by the translator this run (billable). */
+        translatedThisRun?: number;
+    };
+    locales: LocaleReport[];
+    /** Every key that failed, across locales. Non-empty means the run is partial. */
+    translationFailures: TranslationFailure[];
+    warnings: Array<{
+        type: string;
+        file: string;
+        line?: number;
+        message: string;
+    }>;
+    /** Finalization notes (dependencies added, config created, …). */
+    notes: string[];
+    /** The project's prettier/biome run on changed files, if it has one. */
+    formatter?: FormatResult;
+    /** Warnings/errors the engine logged while running. */
+    engineLog: Array<{
+        level: 'warn' | 'error';
+        message: string;
+    }>;
+    lockfile: string;
+    /**
+     * True when the lockfile is gitignored (`babelize init` adds `.babelize/`):
+     * it still works locally, but teammates and CI won't get it.
+     */
+    lockfileIgnored: boolean;
+    /** Per-key engine metadata (confidence, TM/lockfile origin) by locale. */
+    metadata: Record<string, Record<string, unknown>>;
+    /** source key → source text, and locale → key → translated text. */
+    results: {
+        source: Record<string, string>;
+        targets: Record<string, Record<string, string>>;
+    };
+    /** Epoch ms when the run started. */
+    startedAt: number;
+    durationMs: number;
+}
+/** Normalise `--to fr,de , ja` into a deduped list without the source locale. */
+export declare function parseLocales(raw: string | string[] | undefined, sourceLocale: string): string[];
+export declare function validateLocales(sourceLocale: string, targetLocales: string[]): void;
+/**
+ * Engine log lines that are wrong or redundant for a local run: the
+ * TRANSLATOR_URL check doesn't know about BYOK/injected providers, and the
+ * "run your install" hint is already a finalization note in the summary.
+ */
+/** `msg` as one sentence: trailing dots/spaces trimmed, exactly one period added. */
+export declare function sentence(msg: string): string;
+export declare function isEngineLogNoise(message: string): boolean;
+export declare function buildLocaleReports(targetLocales: string[], source: Record<string, string>, targets: Record<string, Record<string, string>>, failures?: TranslationFailure[], metadata?: Record<string, Record<string, unknown>>): LocaleReport[];
+/**
+ * Run the Babelize engine on a temp copy of `projectDir` and, unless
+ * `dryRun`, apply the result back to the working tree. The project is never
+ * touched until the engine has finished successfully and every target locale
+ * has translations.
+ */
+export declare function runLocalTranslate(opts: LocalTranslateOptions, deps?: LocalTranslateDeps): Promise<LocalTranslateReport>;