@babelize/engine 0.0.0-stage → 0.1.2

package/dist/local/provider.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOSTED_PROVIDER_ID = exports.BABELIZE_KEY_ENV_VAR = exports.PROVIDER_ENV_VARS = void 0;
+exports.isHostedResolution = isHostedResolution;
+exports.isByokProvider = isByokProvider;
+exports.noKeyMessage = noKeyMessage;
+exports.resolveProvider = resolveProvider;
+const types_1 = require("@babelize/types");
+const hosted_provider_1 = require("./hosted-provider");
+/**
+ * Env var holding each provider's key, in auto-detection order: the first one
+ * set wins when `--provider` isn't given.
+ */
+exports.PROVIDER_ENV_VARS = [
+    { provider: 'anthropic', envVar: 'ANTHROPIC_API_KEY' },
+    { provider: 'openai', envVar: 'OPENAI_API_KEY' },
+    { provider: 'gemini', envVar: 'GEMINI_API_KEY' },
+    { provider: 'groq', envVar: 'GROQ_API_KEY' },
+    { provider: 'openrouter', envVar: 'OPENROUTER_API_KEY' },
+];
+/** Env var holding a Babelize API key for hosted translation. */
+exports.BABELIZE_KEY_ENV_VAR = 'BABELIZE_API_KEY';
+/** `--provider` value selecting Babelize-hosted translation. */
+exports.HOSTED_PROVIDER_ID = 'babelize';
+function isHostedResolution(r) {
+    return r.provider === exports.HOSTED_PROVIDER_ID;
+}
+function isByokProvider(value) {
+    return types_1.BYOK_PROVIDERS.includes(value);
+}
+function envVarFor(provider) {
+    return exports.PROVIDER_ENV_VARS.find((p) => p.provider === provider).envVar;
+}
+/** Message shown when no key is available. Lists env vars, never values. */
+function noKeyMessage() {
+    return [
+        'No translation key found. Set one of these to use your own LLM key:',
+        ...exports.PROVIDER_ENV_VARS.map((p) => `  ${p.envVar.padEnd(20)} (${types_1.PROVIDER_DEFINITIONS[p.provider].name})`),
+        `or create a Babelize API key at ${hosted_provider_1.API_KEYS_URL} and set ${exports.BABELIZE_KEY_ENV_VAR} (free tier included).`,
+    ].join('\n');
+}
+function hosted(env, model, autoDetected) {
+    if (model) {
+        return {
+            ok: false,
+            code: 'model_not_supported',
+            message: '--model applies to your own LLM key only; Babelize-hosted translation picks the model on the server.',
+        };
+    }
+    const apiKey = env[exports.BABELIZE_KEY_ENV_VAR]?.trim();
+    if (!apiKey) {
+        return {
+            ok: false,
+            code: 'missing_key',
+            message: `--provider ${exports.HOSTED_PROVIDER_ID} needs ${exports.BABELIZE_KEY_ENV_VAR} to be set. Create a key at ${hosted_provider_1.API_KEYS_URL}.`,
+        };
+    }
+    return { ok: true, value: { provider: exports.HOSTED_PROVIDER_ID, apiKey, envVar: exports.BABELIZE_KEY_ENV_VAR, autoDetected } };
+}
+/**
+ * Pick the translator, in order of precedence:
+ * 1. `--provider` (a BYOK vendor, or `babelize`); its env var must be set.
+ * 2. The first BYOK env var set, in PROVIDER_ENV_VARS order.
+ * 3. BABELIZE_API_KEY → Babelize-hosted translation.
+ * For BYOK the model is `--model` or the provider's default from
+ * @babelize/types; hosted translation's model is chosen by the server.
+ */
+function resolveProvider(opts, env = process.env) {
+    const model = opts.model?.trim() || undefined;
+    if (opts.provider) {
+        const requested = opts.provider.trim().toLowerCase();
+        if (requested === exports.HOSTED_PROVIDER_ID)
+            return hosted(env, model, false);
+        if (!isByokProvider(requested)) {
+            return {
+                ok: false,
+                code: 'unknown_provider',
+                message: `Unknown provider "${opts.provider}". Use one of: ${[...exports.PROVIDER_ENV_VARS.map((p) => p.provider), exports.HOSTED_PROVIDER_ID].join(', ')}.`,
+            };
+        }
+        const envVar = envVarFor(requested);
+        const apiKey = env[envVar]?.trim();
+        if (!apiKey) {
+            return {
+                ok: false,
+                code: 'missing_key',
+                message: `--provider ${requested} needs ${envVar} to be set.`,
+            };
+        }
+        return {
+            ok: true,
+            value: {
+                provider: requested,
+                apiKey,
+                model: model ?? types_1.PROVIDER_DEFINITIONS[requested].defaultModel,
+                envVar,
+                autoDetected: false,
+            },
+        };
+    }
+    for (const { provider, envVar } of exports.PROVIDER_ENV_VARS) {
+        const apiKey = env[envVar]?.trim();
+        if (apiKey) {
+            return {
+                ok: true,
+                value: {
+                    provider,
+                    apiKey,
+                    model: model ?? types_1.PROVIDER_DEFINITIONS[provider].defaultModel,
+                    envVar,
+                    autoDetected: true,
+                },
+            };
+        }
+    }
+    if (env[exports.BABELIZE_KEY_ENV_VAR]?.trim())
+        return hosted(env, model, true);
+    return { ok: false, code: 'no_key', message: noKeyMessage() };
+}

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

@@ -0,0 +1,18 @@
+import type { KeyFailure, KeyResult, TranslationBatchRequest, TranslationProvider } from '../providers/types';
+export { isPseudoLocalized, PSEUDO_CLOSE, PSEUDO_OPEN } from '../utils/pseudo-markers';
+export interface PseudoProviderOptions {
+    /**
+     * Fail chosen keys, to exercise partial runs: return a failure for the
+     * (key, locale) or null to translate it.
+     */
+    fail?: (key: string, locale: string) => KeyFailure | null;
+}
+export declare class PseudoTranslationProvider implements TranslationProvider {
+    private readonly options;
+    /** Output is pseudo-localization: the lockfile marks it and a real run replaces it. */
+    readonly pseudo = true;
+    /** Every request received, in order. */
+    readonly calls: TranslationBatchRequest[];
+    constructor(options?: PseudoProviderOptions);
+    translateBatch(request: TranslationBatchRequest): Promise<KeyResult[]>;
+}

package/dist/local/pseudo-provider.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PseudoTranslationProvider = exports.PSEUDO_OPEN = exports.PSEUDO_CLOSE = exports.isPseudoLocalized = void 0;
+const icu_message_1 = require("../utils/icu-message");
+const rules_1 = require("../modules/glossary/rules");
+/**
+ * Pseudo-localization: a deterministic, offline TranslationProvider for tests
+ * and for checking i18n wiring without an API key (`babelize translate
+ * --provider pseudo`). It never produces a real translation.
+ *
+ * "Save note" → "⟦Sávé ñóté⟧". Placeholder tokens (`[#VAR_0#]`), `{args}`,
+ * tags, URLs, code and identifiers are kept verbatim; glossary terms come out
+ * as their required translation. ICU plurals get exactly the categories the
+ * target locale needs, and a key the engine marks as a count (it sends a
+ * pluralization hint) comes back as an ICU plural (`one`/`other` for de, plain
+ * text for ja, six forms for ar). So the engine's validators accept the
+ * output, as they would a good LLM's.
+ */
+const pseudo_markers_1 = require("../utils/pseudo-markers");
+var pseudo_markers_2 = require("../utils/pseudo-markers");
+Object.defineProperty(exports, "isPseudoLocalized", { enumerable: true, get: function () { return pseudo_markers_2.isPseudoLocalized; } });
+Object.defineProperty(exports, "PSEUDO_CLOSE", { enumerable: true, get: function () { return pseudo_markers_2.PSEUDO_CLOSE; } });
+Object.defineProperty(exports, "PSEUDO_OPEN", { enumerable: true, get: function () { return pseudo_markers_2.PSEUDO_OPEN; } });
+const ACCENTS = {
+    a: 'á', e: 'é', i: 'í', o: 'ó', u: 'ú', y: 'ý', c: 'ç', n: 'ñ',
+    A: 'Á', E: 'É', I: 'Í', O: 'Ó', U: 'Ú', Y: 'Ý', C: 'Ç', N: 'Ñ',
+};
+/** Spans that must survive untouched: engine tokens, args, tags, URLs, emails, code, identifiers. */
+const PROTECTED = new RegExp([
+    String.raw `\[\s*#\s*VAR_\d+\s*#\s*\]`,
+    // printf / gettext placeholders and HTML entities: %(name)s, %d, %%, —
+    String.raw `%\(\w+\)[-#0 +]*\d*(?:\.\d+)?[sdifr]|%%|%[sdif]`,
+    String.raw `&(?:[a-zA-Z][a-zA-Z0-9]{1,31}|#\d{1,7}|#x[0-9a-fA-F]{1,6});`,
+    String.raw `\{[^{}]*\}`,
+    String.raw `<[^<>]+>`,
+    String.raw `https?:\/\/\S+`,
+    String.raw `[\w.+-]+@[\w-]+\.[\w.]+`,
+    '`[^`]+`',
+    String.raw `--?[a-z][\w-]*`,
+    String.raw `\b\w+\.\w+\b`,
+    String.raw `\b[A-Za-z]*[\d_][\w-]*`,
+    String.raw `\b[A-Z][A-Z0-9]+\b`,
+].join('|'), 'g');
+function accent(text) {
+    return text.replace(/[aeiouycnAEIOUYCN]/g, (ch) => ACCENTS[ch] ?? ch);
+}
+/** Accent everything outside protected spans; glossary terms become their required translation. */
+function pseudoText(text, glossary = []) {
+    const terms = [...glossary].sort((a, b) => b.term.length - a.term.length);
+    // Glossary terms in plain text become their required translation, unaccented.
+    const plain = (segment) => {
+        let out = '';
+        let rest = segment;
+        while (rest) {
+            let best = null;
+            for (const g of terms) {
+                const m = new RegExp((0, rules_1.termPattern)(g.term), 'iu').exec(rest);
+                if (m && (!best || m.index < best.index))
+                    best = { index: m.index, length: m[0].length, translation: g.translation };
+            }
+            if (!best)
+                return out + accent(rest);
+            out += accent(rest.slice(0, best.index)) + best.translation;
+            rest = rest.slice(best.index + best.length);
+        }
+        return out;
+    };
+    let out = '';
+    let last = 0;
+    for (const m of text.matchAll(PROTECTED)) {
+        out += plain(text.slice(last, m.index)) + m[0];
+        last = m.index + m[0].length;
+    }
+    return out + plain(text.slice(last));
+}
+/** True when the text is an ICU message (plural/select/selectordinal argument). */
+function isIcu(text) {
+    return /\{\s*[\w.]+\s*,\s*(plural|select|selectordinal)\s*,/.test(text);
+}
+/**
+ * Pseudo-localize an ICU message: literal text accented, arguments kept,
+ * plural/selectordinal branches rebuilt for the locale's categories (a
+ * missing category reuses the `other` branch; `=N` branches are kept).
+ */
+function pseudoIcu(msg, locale, glossary) {
+    let i = 0;
+    const message = () => {
+        let out = '';
+        let text = '';
+        const flush = () => {
+            out += pseudoText(text, glossary);
+            text = '';
+        };
+        while (i < msg.length && msg[i] !== '}') {
+            if (msg[i] === '{') {
+                flush();
+                out += argument();
+            }
+            else if (msg[i] === "'" && /['{}#|]/.test(msg[i + 1] ?? '')) {
+                // ICU quoting ('{' … ', or '' for an apostrophe): copy verbatim.
+                const end = msg[i + 1] === "'" ? i + 1 : msg.indexOf("'", i + 1);
+                const stop = end === -1 ? msg.length : end + 1;
+                flush();
+                out += msg.slice(i, stop);
+                i = stop;
+            }
+            else {
+                text += msg[i++];
+            }
+        }
+        flush();
+        return out;
+    };
+    const argument = () => {
+        const start = i;
+        i++; // {
+        const head = /^\s*([\w.]+)\s*(?:,\s*(\w+)\s*(?:,)?)?/.exec(msg.slice(i));
+        const [, name, type] = head;
+        if (type !== 'plural' && type !== 'selectordinal' && type !== 'select') {
+            // Simple or formatted argument: copy as is, to its closing brace.
+            let depth = 1;
+            i = start + 1;
+            while (i < msg.length && depth > 0) {
+                if (msg[i] === '{')
+                    depth++;
+                else if (msg[i] === '}')
+                    depth--;
+                i++;
+            }
+            return msg.slice(start, i);
+        }
+        i += head[0].length;
+        const branches = [];
+        let offset = '';
+        for (;;) {
+            const sel = /^\s*(offset:\s*\d+|=?[\w-]+)\s*/.exec(msg.slice(i));
+            if (!sel)
+                break;
+            i += sel[0].length;
+            if (sel[1].startsWith('offset:')) {
+                offset = `${sel[1]} `;
+                continue;
+            }
+            if (msg[i] !== '{')
+                break;
+            i++;
+            const body = message();
+            i++; // }
+            branches.push({ selector: sel[1], body });
+        }
+        while (i < msg.length && msg[i] !== '}')
+            i++;
+        i++; // closing } of the argument
+        let out = branches;
+        if (type !== 'select') {
+            const needed = type === 'plural' ? (0, icu_message_1.requiredPluralCategories)(locale).cardinal : (0, icu_message_1.requiredPluralCategories)(locale).ordinal;
+            const other = branches.find((b) => b.selector === 'other') ?? branches[branches.length - 1];
+            out = [
+                ...branches.filter((b) => b.selector.startsWith('=')),
+                ...needed.map((c) => branches.find((b) => b.selector === c) ?? { selector: c, body: other.body }),
+            ];
+        }
+        return `{${name}, ${type}, ${offset}${out.map((b) => `${b.selector} {${b.body}}`).join(' ')}}`;
+    };
+    return message();
+}
+/** The count argument named by the engine's pluralization hint, if any. */
+function countArgFromHint(hint) {
+    if (!hint || !/ICU plural/.test(hint))
+        return undefined;
+    return /^\{([\w.]+)\}/.exec(hint)?.[1];
+}
+/** `You have {count} notes` → `{count, plural, one {⟦… # …⟧} other {⟦… # …⟧}}` for the locale's categories. */
+function pseudoPlural(text, arg, locale, glossary) {
+    const categories = (0, icu_message_1.requiredPluralCategories)(locale).cardinal;
+    const body = `${pseudo_markers_1.PSEUDO_OPEN}${pseudoText(text, glossary)}${pseudo_markers_1.PSEUDO_CLOSE}`;
+    if (categories.length <= 1)
+        return body;
+    const branch = body.split(`{${arg}}`).join('#');
+    return `{${arg}, plural, ${categories.map((c) => `${c} {${branch}}`).join(' ')}}`;
+}
+class PseudoTranslationProvider {
+    constructor(options = {}) {
+        this.options = options;
+        /** Output is pseudo-localization: the lockfile marks it and a real run replaces it. */
+        this.pseudo = true;
+        /** Every request received, in order. */
+        this.calls = [];
+    }
+    async translateBatch(request) {
+        this.calls.push(request);
+        const locale = request.targetLocale ?? request.targetLang;
+        const glossary = request.glossary ?? [];
+        return request.entries.map((entry) => {
+            const failure = this.options.fail?.(entry.key, locale);
+            if (failure)
+                return { key: entry.key, status: 'failed', ...failure };
+            const arg = countArgFromHint(request.hints?.[entry.key]);
+            const value = arg
+                ? pseudoPlural(entry.value, arg, locale, glossary)
+                : isIcu(entry.value)
+                    ? `${pseudo_markers_1.PSEUDO_OPEN}${pseudoIcu(entry.value, locale, glossary)}${pseudo_markers_1.PSEUDO_CLOSE}`
+                    : `${pseudo_markers_1.PSEUDO_OPEN}${pseudoText(entry.value, glossary)}${pseudo_markers_1.PSEUDO_CLOSE}`;
+            return { key: entry.key, status: 'ok', value, confidence: 1, engine: 'pseudo' };
+        });
+    }
+}
+exports.PseudoTranslationProvider = PseudoTranslationProvider;

package/dist/local/report.d.ts

@@ -0,0 +1,177 @@
+import type { KeyFailureReason } from '../providers/types';
+import type { FormatResult } from './formatter';
+import type { FrameworkStatus, LocalTranslateReport } from './translate-core';
+import type { FileDiffStat } from './workspace-copy';
+/**
+ * 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.
+ */
+export declare const TRANSLATE_REPORT_SCHEMA_VERSION = 1;
+export declare const TRANSLATE_REPORT_SCHEMA_ID = "https://babelize.co/schemas/translate-report.v1.json";
+/** Default report location, relative to the project root. */
+export declare const DEFAULT_REPORT_FILE = ".babelize/local/report.json";
+/** Keeps the report out of git while the lockfile next to it stays committed. */
+export declare const BABELIZE_GITIGNORE = ".babelize/.gitignore";
+/** One key in one locale. */
+export type KeyStatus = 
+/** Translated, no QA notes. */
+'translated'
+/** Translated with QA warnings (glossary, length, backup translator…). */
+ | 'warning'
+/** Has a value identical to the source text: fine for names and codes, otherwise review it. */
+ | 'unchanged'
+/** The translator could not translate it this run; not written, retried next run. */
+ | 'failed'
+/** No value in this locale and no failure recorded (e.g. a dry run of a locale left out). */
+ | 'missing';
+export interface TranslateReportKeyLocale {
+    status: KeyStatus;
+    /** The value in the locale file (absent when failed/missing). */
+    value?: string;
+    reason?: KeyFailureReason;
+    message?: string;
+    retryable?: boolean;
+    warnings?: string[];
+}
+export interface TranslateReportLocale {
+    locale: string;
+    /** `failed` if any key failed, `warning` for QA warnings or missing keys, else `ok`. */
+    status: 'ok' | 'warning' | 'failed';
+    total: number;
+    translated: number;
+    missing: number;
+    failed: number;
+    qaWarnings: number;
+    sameAsSource: number;
+}
+export interface TranslateReport {
+    $schema: string;
+    schemaVersion: typeof TRANSLATE_REPORT_SCHEMA_VERSION;
+    /** False when any key failed: the run is partial (`babelize translate` exits 6). */
+    ok: boolean;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    framework: string;
+    frameworkStatus: FrameworkStatus;
+    /** Null when a translator was injected (tests, embedding). */
+    provider: {
+        provider: string;
+        name: string;
+        model?: string;
+    } | null;
+    sourceLocale: string;
+    targetLocales: string[];
+    keptLocales: string[];
+    droppedLocales: string[];
+    dryRun: boolean;
+    applied: boolean;
+    filesChanged: {
+        added: string[];
+        modified: string[];
+        deleted: string[];
+    };
+    diffSummary: FileDiffStat[];
+    /** Unified diff, dry runs only. */
+    diff?: string;
+    stats: LocalTranslateReport['stats'];
+    summary: {
+        sourceKeys: number;
+        /** (key, locale) values present after the run. */
+        translations: number;
+        /** (key, locale) translations produced by the translator this run. */
+        newTranslations: number;
+        /** (key, locale) values reused from the lockfile, translation memory or cache. */
+        reused: number;
+        failed: number;
+        qaWarnings: number;
+        missing: number;
+        unchanged: number;
+        notInjected: number;
+    };
+    locales: TranslateReportLocale[];
+    failures: {
+        total: number;
+        items: Array<{
+            locale: string;
+            key: string;
+            source: string;
+            reason: KeyFailureReason;
+            retryable: boolean;
+            message?: string;
+        }>;
+    };
+    qaWarnings: {
+        total: number;
+        items: Array<{
+            locale: string;
+            key: string;
+            warnings: string[];
+        }>;
+    };
+    /** Keys without a value that did not fail this run (failures are listed under `failures`). */
+    missing: {
+        total: number;
+        items: Array<{
+            locale: string;
+            key: string;
+        }>;
+    };
+    unchanged: {
+        total: number;
+        items: Array<{
+            locale: string;
+            key: string;
+            value: string;
+        }>;
+    };
+    notInjected: {
+        total: number;
+        items: Array<{
+            file: string;
+            key: string;
+            text: string;
+            reason: string;
+        }>;
+    };
+    unusedKeys: {
+        total: number;
+        items: string[];
+    };
+    dynamicKeyFiles: string[];
+    /** Every source key with its outcome per target locale. */
+    keys: Array<{
+        key: string;
+        source: string;
+        locales: Record<string, TranslateReportKeyLocale>;
+    }>;
+    warnings: Array<{
+        type: string;
+        file: string;
+        line?: number;
+        message: string;
+    }>;
+    notes: string[];
+    engineLog: Array<{
+        level: 'warn' | 'error';
+        message: string;
+    }>;
+    formatter?: FormatResult;
+    lockfile: string;
+    lockfileIgnored: boolean;
+}
+/** The report of a finished run (`r` from runLocalTranslate). */
+export declare function buildTranslateReport(r: LocalTranslateReport): TranslateReport;
+/**
+ * Write the report as JSON. `file` is resolved against `projectDir`
+ * (default {@link DEFAULT_REPORT_FILE}); returns the absolute path written.
+ */
+export declare function writeTranslateReport(projectDir: string, report: TranslateReport, file?: string): Promise<string>;
+/**
+ * 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.
+ */
+export declare function ensureReportGitignored(root: string): Promise<boolean>;