@babelize/engine 0.0.0-stage → 0.1.2

package/dist/modules/translator/client/retry.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry503 = exports.ProviderHttpError = void 0;
+exports.parseRetryAfter = parseRetryAfter;
+exports.isRetryable = isRetryable;
+exports.withRetry = withRetry;
+function abortError() {
+    const err = new Error('Translation request aborted');
+    err.name = 'AbortError';
+    return err;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(abortError());
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError());
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** An HTTP error from a translation API, carrying what retry decisions need. */
+class ProviderHttpError extends Error {
+    constructor(message, status, 
+    /** Server-requested wait from a Retry-After header, in ms. */
+    retryAfterMs) {
+        super(message);
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'ProviderHttpError';
+    }
+}
+exports.ProviderHttpError = ProviderHttpError;
+/** Parse a Retry-After header (seconds or HTTP date) into milliseconds. */
+function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(header);
+    if (!Number.isNaN(date))
+        return Math.max(0, date - Date.now());
+    return undefined;
+}
+/**
+ * Retry only what can succeed on a second try: timeouts, network errors,
+ * 408/409/425/429 and 5xx. Auth, bad request and unknown model (other 4xx)
+ * fail immediately — retrying a bad key just delays the error.
+ */
+function isRetryable(err) {
+    if (err instanceof ProviderHttpError) {
+        return err.status >= 500 || [408, 409, 425, 429].includes(err.status);
+    }
+    return true;
+}
+async function withRetry(fn, opts) {
+    const maxDelay = opts.maxDelayMs ?? 60000;
+    let attempt = 0;
+    const outer = opts.signal;
+    while (true) {
+        if (outer?.aborted)
+            throw abortError();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+        const onAbort = () => controller.abort();
+        outer?.addEventListener('abort', onAbort, { once: true });
+        try {
+            return await fn(controller.signal);
+        }
+        catch (err) {
+            if (outer?.aborted)
+                throw abortError();
+            attempt += 1;
+            if (attempt > opts.maxRetries || !isRetryable(err))
+                throw err;
+            const backoff = opts.baseDelayMs * Math.pow(2, attempt - 1);
+            const requested = err instanceof ProviderHttpError ? err.retryAfterMs : undefined;
+            const delay = Math.min(maxDelay, Math.max(backoff, requested ?? 0));
+            await sleep(delay, outer);
+        }
+        finally {
+            clearTimeout(timer);
+            outer?.removeEventListener('abort', onAbort);
+        }
+    }
+}
+/** @deprecated Use withRetry — kept for existing callers. */
+exports.withRetry503 = withRetry;

package/dist/modules/translator/client/test-utils/mock.client.d.ts

@@ -0,0 +1,31 @@
+import type { TranslatorClient } from '../translator.interface';
+import type { HFTranslateRequest, HFTranslateResponse } from '../request.types';
+/**
+ * Mock translator client for unit tests.
+ *
+ * - `health()` / `warmup()` → always succeed (configurable)
+ * - `translate()` → deterministic: prefixes each value with `[targetLang]`
+ * - `calls` array records every invocation for assertion
+ *
+ * Usage:
+ *   const mock = new MockTranslatorClient();
+ *   // … run code under test …
+ *   expect(mock.calls.length).toBe(2);
+ */
+export declare class MockTranslatorClient implements TranslatorClient {
+    /** Every translate() call is pushed here for inspection. */
+    readonly calls: HFTranslateRequest[];
+    /** Configure health() return value. */
+    healthResult: boolean;
+    /** Configure warmup() return value. */
+    warmupResult: boolean;
+    /** If set, translate() will throw this error. */
+    translateError: Error | null;
+    /** Custom translate handler — overrides default deterministic behaviour. */
+    translateHandler: ((req: HFTranslateRequest) => HFTranslateResponse) | null;
+    health(): Promise<boolean>;
+    warmup(): Promise<boolean>;
+    translate(req: HFTranslateRequest): Promise<HFTranslateResponse>;
+    /** Reset call history and configuration. */
+    reset(): void;
+}

package/dist/modules/translator/client/test-utils/mock.client.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockTranslatorClient = void 0;
+/**
+ * Mock translator client for unit tests.
+ *
+ * - `health()` / `warmup()` → always succeed (configurable)
+ * - `translate()` → deterministic: prefixes each value with `[targetLang]`
+ * - `calls` array records every invocation for assertion
+ *
+ * Usage:
+ *   const mock = new MockTranslatorClient();
+ *   // … run code under test …
+ *   expect(mock.calls.length).toBe(2);
+ */
+class MockTranslatorClient {
+    constructor() {
+        /** Every translate() call is pushed here for inspection. */
+        this.calls = [];
+        /** Configure health() return value. */
+        this.healthResult = true;
+        /** Configure warmup() return value. */
+        this.warmupResult = true;
+        /** If set, translate() will throw this error. */
+        this.translateError = null;
+        /** Custom translate handler — overrides default deterministic behaviour. */
+        this.translateHandler = null;
+    }
+    async health() {
+        return this.healthResult;
+    }
+    async warmup() {
+        return this.warmupResult;
+    }
+    async translate(req) {
+        this.calls.push(req);
+        if (this.translateError)
+            throw this.translateError;
+        if (this.translateHandler)
+            return this.translateHandler(req);
+        // Deterministic: prefix each value with the target language code
+        return {
+            translations: req.entries.map((e) => ({
+                key: e.key,
+                value: `[${req.targetLang}] ${e.value}`,
+            })),
+            model: 'mock-nllb-200',
+        };
+    }
+    /** Reset call history and configuration. */
+    reset() {
+        this.calls.length = 0;
+        this.healthResult = true;
+        this.warmupResult = true;
+        this.translateError = null;
+        this.translateHandler = null;
+    }
+}
+exports.MockTranslatorClient = MockTranslatorClient;

package/dist/modules/translator/client/translator.interface.d.ts

@@ -0,0 +1 @@
+export type { TranslatorClient } from '../../../types';

package/dist/modules/translator/client/translator.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/modules/translator/icu-branches.d.ts

@@ -0,0 +1,138 @@
+/**
+ * ICU plural/select messages for plain-text machine translation (NLLB).
+ *
+ * NLLB translates sentences, not ICU syntax. So an ICU message is taken apart
+ * into the plain sentences it can render, each sentence is translated on its
+ * own, and the translations are put back together as an ICU message for the
+ * target language:
+ *
+ * - Text around a selector is moved into its branches, so every translated
+ *   unit is a whole sentence ("You have {count, plural, one {# file} other
+ *   {# files}}." → one {You have # file.} other {You have # files.}).
+ * - A plural gets the TARGET language's CLDR categories (Polish one/few/many/
+ *   other, Japanese only other). Each category is translated from the source
+ *   branch of the same name, or the source `other`; exact `=n` branches stay.
+ * - The count (`#`, `{count}`, or a gettext `%(count)d`) is replaced by a real
+ *   number of that category (Polish few → 2, many → 5, Arabic many → 11), so
+ *   the translator inflects the words around it. The same number must come
+ *   back exactly where it can be turned back into the count; if it doesn't,
+ *   that branch — and so the message — fails.
+ * - `select` branches keep their keys; nested selectors are expanded the same
+ *   way. Anything that can't be expressed fails with a reason; a message is
+ *   never put together from a partial set of branches.
+ *
+ * Infrastructure-free: the caller sends the units to its translator and hands
+ * the per-unit results back to `compose`.
+ */
+import { type IcuNode } from '../../utils/icu-message';
+import { type FixedTerm } from '../../utils/placeholder-protection';
+import type { KeyFailure, KeyResult } from '../../providers/types';
+/** Leaves (translated sentences) one message may expand to. */
+export declare const MAX_BRANCH_UNITS = 64;
+type Selector = Extract<IcuNode, {
+    options: unknown;
+}>;
+type SelectorType = Selector['type'];
+/** A number standing in for a plural's value in one unit. */
+interface NumberSlot {
+    /** As written in the text sent to the translator, e.g. "5" or "1.5". */
+    text: string;
+    /** Occurrences in the sent text; the translation must have exactly as many. */
+    count: number;
+    /** What each occurrence turns back into (a sentinel). */
+    restore: string;
+    /** For messages: "#", "{count}", "%(count)d". */
+    label: string;
+    /**
+     * The branch stands for this one number only (`=1`, German/Polish "one",
+     * Arabic "zero"/"two"): the translation may spell it out ("eine Datei")
+     * instead of showing it, and the branch is still exact.
+     */
+    mayBeSpelledOut: boolean;
+}
+export interface BranchUnit {
+    /** Unique within the plan. */
+    id: string;
+    /** Which branch combination, e.g. "count=few" ("message" with no selectors). */
+    label: string;
+    /** Text for the translator: protected spans as [#VAR_n#] tokens, counts as numbers. */
+    sendText: string;
+    tokens: string[];
+    /** What each token is restored to (a fixed glossary term becomes its translation). */
+    restore: string[];
+    slots: NumberSlot[];
+    /** Units with nothing to translate (only a number, tags, placeholders) are not sent. */
+    passthrough: boolean;
+    /** Formatted arguments of the unit, by sentinel index. */
+    args: string[];
+    /** Literal text restored verbatim (gettext count placeholders), by sentinel index. */
+    literals: string[];
+    /** The unit's parent selector is a plural: `#` and quoting follow plural rules. */
+    inPlural: boolean;
+    /** For a passthrough unit: the text with sentinels, used as is. */
+    sentinelText: string;
+    /** Spaces were put between a count and a token it touches (see makeUnit). */
+    spaced: boolean;
+}
+export type BranchFailure = {
+    ok: false;
+    reason: KeyFailure['reason'];
+    retryable: boolean;
+    message: string;
+};
+export type BranchComposeResult = {
+    ok: true;
+    value: string;
+} | BranchFailure;
+export interface BranchPlan {
+    units: BranchUnit[];
+    /**
+     * Put the message together from one translator result per unit (by unit
+     * id). `checkUnit` adds the caller's own per-branch checks (e.g. "came back
+     * untranslated"); it returns a problem message or null.
+     */
+    compose(results: Map<string, KeyResult | undefined>, checkUnit?: (unit: BranchUnit, translated: string) => BranchFailure | null): BranchComposeResult;
+}
+export interface PlanOptions {
+    neverTranslateTerms?: string[];
+    /** "Always translate as" terms: tokenized, and restored to their translation. */
+    fixedTerms?: FixedTerm[];
+    /**
+     * Literal text standing for the value of the plural it appears in, besides
+     * `#` — e.g. "%(count)d" in a gettext plural turned into ICU.
+     */
+    valuePlaceholder?: string;
+    /**
+     * Plain (non-ICU) source: wrap it in a plural over each of these arguments
+     * for the target language (target-side plurals for `{count} files`).
+     */
+    pluralizeArgs?: string[];
+}
+/** Plural categories of a locale, CLDR order. */
+export declare function targetCategories(locale: string, type: 'cardinal' | 'ordinal'): string[];
+/** Candidate numbers for a category (or the exact value of an `=n` branch). */
+declare function numbersFor(locale: string, type: SelectorType, key: string): number[];
+/**
+ * Plan the branch-by-branch translation of `source` into `targetLocale`, or
+ * explain why it can't be done.
+ */
+export declare function planIcuBranches(source: string, targetLocale: string, options?: PlanOptions): BranchPlan | {
+    error: string;
+};
+/** "١٢" → "12", "1,5" → "1.5". */
+declare function normalizeNumber(s: string): string;
+/** Replace each slot's number in the translation by its sentinel; null when a number is missing or repeated. */
+declare function restoreNumbers(translated: string, slots: NumberSlot[]): {
+    text: string;
+} | {
+    problem: string;
+};
+/** ICU-escape literal text: apostrophes before syntax, and `{`, `}` (and `#` in a plural) quoted. */
+export declare function escapeIcuText(text: string, inPlural: boolean): string;
+/** Exposed for tests. */
+export declare const __test: {
+    normalizeNumber: typeof normalizeNumber;
+    restoreNumbers: typeof restoreNumbers;
+    numbersFor: typeof numbersFor;
+};
+export {};