@poco-ai/agentero-dsh-host 0.0.0-stage → 0.1.0

package/lib/translation/mask.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Protect tokens that MT engines mangle (inline math, LaTeX commands, URLs,
+ * DOIs, citation markers, cross-references, and Markdown links) by swapping
+ * them for opaque placeholders before the request and restoring them afterwards.
+ */
+export type MaskedToken = {
+    placeholder: string;
+    original: string;
+};
+export type MaskedText = {
+    text: string;
+    tokens: MaskedToken[];
+};
+export type RestoredText = {
+    text: string;
+    /** Placeholders the engine dropped or rewrote; caller decides retry policy. */
+    missing: number;
+    /** Duplicated or invented placeholders invalidate structural restoration. */
+    invalid?: boolean;
+};
+export declare function maskInlineTokens(text: string): MaskedText;
+export declare function restoreInlineTokens(text: string, tokens: readonly MaskedToken[]): RestoredText;

package/lib/translation/mask.js

@@ -0,0 +1,69 @@
+// Ported from motif (Copyright (c) 2026 poco-ai, MIT). See MOTIF-LICENSE.txt.
+/**
+ * Protect tokens that MT engines mangle (inline math, LaTeX commands, URLs,
+ * DOIs, citation markers, cross-references, and Markdown links) by swapping
+ * them for opaque placeholders before the request and restoring them afterwards.
+ */
+import { findPreservedLinkSpans } from "./preserved-links.js";
+/**
+ * Mathematical white square brackets: absent from paper prose, and left alone
+ * by MT engines far more reliably than ASCII brackets, which collide with
+ * citation markers and with the `[[n]]` batch numbering.
+ */
+function placeholderFor(index) {
+    return `⟦${index}⟧`;
+}
+const MASK_PATTERNS = [
+    /⟪(?:F|\/?S)\d+⟫/gu,
+    // Display / inline TeX math (present when the source came from LaTeX).
+    /\$\$[^$]{1,400}\$\$/g,
+    /\$[^$\n]{1,200}\$/g,
+    /\\\((?:[^\\]|\\[^)]){1,200}?\\\)/g,
+    // LaTeX commands with or without a braced argument.
+    /\\[A-Za-z]+(?:\{[^{}]{0,120}\})?/g,
+    // Links and identifiers.
+    /https?:\/\/[^\s、，。]+/g,
+    /\bdoi:\s*10\.\d{4,9}\/\S+/gi,
+    /\b10\.\d{4,9}\/[^\s、，。]+/g,
+];
+export function maskInlineTokens(text) {
+    // Match the original string once; overlapping patterns must not nest placeholders.
+    const spans = findPreservedLinkSpans(text).map(({ start, end, text }) => ({ start, end, text }));
+    for (const pattern of [...MASK_PATTERNS, /`[^`\n]+`/g, /⟦\s*\d+\s*⟧/g, /\[\[\d+\]\]/g]) {
+        for (const match of text.matchAll(new RegExp(pattern.source, pattern.flags))) {
+            spans.push({ start: match.index, end: match.index + match[0].length, text: match[0] });
+        }
+    }
+    spans.sort((a, b) => a.start - b.start || b.end - a.end);
+    const tokens = [];
+    let cursor = 0;
+    let masked = '';
+    let index = 0;
+    for (const span of spans) {
+        if (span.start < cursor)
+            continue;
+        let placeholder = placeholderFor(index++);
+        while (text.includes(placeholder))
+            placeholder = placeholderFor(index++);
+        tokens.push({ placeholder, original: span.text });
+        masked += text.slice(cursor, span.start) + placeholder;
+        cursor = span.end;
+    }
+    return { text: masked + text.slice(cursor), tokens };
+}
+export function restoreInlineTokens(text, tokens) {
+    const originals = new Map(tokens.map(token => [token.placeholder.slice(1, -1), token.original]));
+    const counts = new Map();
+    let invalid = false;
+    // One pass also prevents a literal placeholder in an original formula from being restored twice.
+    const out = text.replace(/⟦\s*(\d+)\s*⟧/g, (full, id) => {
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+        const original = originals.get(id);
+        if (original === undefined || (counts.get(id) ?? 0) > 1)
+            invalid = true;
+        return original ?? full;
+    });
+    const missing = [...originals.keys()].filter(id => !counts.has(id)).length;
+    return { text: out, missing, ...(invalid ? { invalid: true } : {}) };
+}
+//# sourceMappingURL=mask.js.map

package/lib/translation/mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.js","sourceRoot":"","sources":["../../src/translation/mask.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E;;;;GAIG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAoB9D;;;;GAIG;AACH,SAAS,cAAc,CAAC,KAAa;IACpC,OAAO,IAAI,KAAK,GAAG,CAAC;AACrB,CAAC;AAED,MAAM,aAAa,GAAa;IAC/B,mBAAmB;IACnB,uEAAuE;IACvE,sBAAsB;IACtB,oBAAoB;IACpB,mCAAmC;IACnC,oDAAoD;IACpD,mCAAmC;IACnC,yBAAyB;IACzB,uBAAuB;IACvB,6BAA6B;IAC7B,2BAA2B;CAC3B,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,mFAAmF;IACnF,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACjG,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,CAAC,EAAE,CAAC;QACvF,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAC7E,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACzD,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,KAAK,GAAG,MAAM;YAAE,SAAS;QAClC,IAAI,WAAW,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,WAAW,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC;QACzE,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC;QACvD,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAClC,IAAY,EACZ,MAA8B;IAE7B,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACjG,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,iGAAiG;IACjG,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,IAAI,EAAE,EAAU,EAAE,EAAE;QAC9D,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,IAAI,CAAC;QACxE,OAAO,QAAQ,IAAI,IAAI,CAAC;IAC1B,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3E,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACvE,CAAC"}

package/lib/translation/pipeline.d.ts

@@ -0,0 +1,3 @@
+/** Heal PDF ligatures and wrapped words without deleting unclassified page content. */
+export declare function normalizeTranslationSource(raw: string): string;
+export declare function translateDocumentText(input: string, target: string, translate: (text: string) => Promise<string>, signal: AbortSignal): Promise<string>;

package/lib/translation/pipeline.js

@@ -0,0 +1,119 @@
+/** Motif's protection, sentence batching and repair flow, shared by page reflow and selection translation. */
+import { buildNumberedPayload, buildTranslateBatches, parseNumberedTranslation } from './batches.js';
+import { splitTranslationChunks } from './chunks.js';
+import { maskInlineTokens, restoreInlineTokens } from './mask.js';
+import { splitLayoutSentences } from './sentences.js';
+/** Heal PDF ligatures and wrapped words without deleting unclassified page content. */
+export function normalizeTranslationSource(raw) {
+    const ligatures = { 'ff': 'ff', 'fi': 'fi', 'fl': 'fl', 'ffi': 'ffi', 'ffl': 'ffl', 'ſt': 'st', 'st': 'st' };
+    return raw.normalize('NFC').replace(/\u00ad/gu, '')
+        .replace(/[fffiflffifflſtst]/gu, hit => ligatures[hit] ?? hit)
+        .replace(/(\p{Ll})[-\u2010\u2011\u2012\u2013]\s+(\p{Ll}+)/gu, (full, head, tail) => /^(?:and|or|nor|but|to|vs|versus|per|than)$/iu.test(tail) ? full : `${head}${tail}`)
+        .replace(/[^\S\n]+/gu, ' ').trim();
+}
+function restore(text, tokens) {
+    const value = restoreInlineTokens(text, tokens);
+    return value.missing === 0 && !value.invalid && value.text.trim() !== '' ? value.text.trim() : undefined;
+}
+/** Alphabetic aliases avoid models interpreting a numeric placeholder as a value. */
+function aliasFor(index) {
+    return `ZXQ${index.toString(26).replace(/[0-9a-p]/gu, c => String.fromCharCode(65 + Number.parseInt(c, 26)))}QXZ`;
+}
+export async function translateDocumentText(input, target, translate, signal) {
+    // Mask before normalization and sentence cutting so formulas and URLs stay byte-exact.
+    const masked = maskInlineTokens(input);
+    const paragraphs = normalizeTranslationSource(masked.text).split(/\n\s*\n/gu).filter(part => part.trim() !== '');
+    const units = [];
+    for (const [paragraph, text] of paragraphs.entries()) {
+        for (const sentence of splitLayoutSentences(text)) {
+            for (const source of splitTranslationChunks(sentence, 2200)) {
+                units.push({ source, paragraph, index: units.length,
+                    tokens: masked.tokens.filter(token => source.includes(token.placeholder)) });
+            }
+        }
+    }
+    const output = new Array(units.length);
+    const call = async (source) => {
+        signal.throwIfAborted();
+        const result = await translate(source);
+        signal.throwIfAborted();
+        return result;
+    };
+    const gap = /^zh(?:-|$)/iu.test(target) ? '' : ' ';
+    const incomplete = (error) => error instanceof Error
+        && 'code' in error && error.code === 'TRANSLATION_INCOMPLETE';
+    const callUnit = async (source, depth = 0) => {
+        try {
+            return await call(source);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (!incomplete(error) || depth >= 2 || source.length < 64)
+                throw error;
+            const parts = [];
+            for (const part of splitTranslationChunks(source, Math.max(32, Math.ceil(source.length / 2)))) {
+                parts.push(await callUnit(part, depth + 1));
+            }
+            return parts.join(gap);
+        }
+    };
+    const finalize = async (unit, candidate) => {
+        const restored = restore(candidate, unit.tokens);
+        if (restored !== undefined)
+            return restored;
+        const retry = restore(await callUnit(unit.source), unit.tokens);
+        if (retry !== undefined)
+            return retry;
+        const aliases = unit.tokens.map((token, index) => ({ ...token, alias: aliasFor(index) }));
+        let alternate = unit.source;
+        for (const token of aliases)
+            alternate = alternate.replaceAll(token.placeholder, token.alias);
+        alternate = await callUnit(alternate);
+        for (const token of aliases)
+            alternate = alternate.replace(new RegExp(token.alias, 'gi'), token.placeholder);
+        const repaired = restore(alternate, unit.tokens);
+        if (repaired !== undefined)
+            return repaired;
+        // Last resort from motif: translate only prose between protected spans.
+        const parts = unit.source.split(/(⟦\d+⟧)/u);
+        for (const [index, part] of parts.entries()) {
+            if (/^⟦\d+⟧$/u.test(part) || !/\p{L}/u.test(part))
+                continue;
+            const leading = part.match(/^[\s.,;:!?。；，：！？)\]]*/u)?.[0] ?? '';
+            const translated = await callUnit(part.slice(leading.length));
+            // No token was sent in this fragment: invented placeholders are a failure.
+            if (/⟦\s*\d+\s*⟧/u.test(translated))
+                throw new Error('Translation changed protected formulas or links. Please retry.');
+            parts[index] = leading + translated;
+        }
+        const protectedResult = restore(parts.join(' '), unit.tokens);
+        if (protectedResult === undefined)
+            throw new Error('Translation changed protected formulas or links. Please retry.');
+        return protectedResult;
+    };
+    // Serial batches keep repair requests bounded and avoid amplifying provider rate limits.
+    for (const batch of buildTranslateBatches(units)) {
+        signal.throwIfAborted();
+        let segments;
+        try {
+            const result = batch.length === 1 ? await callUnit(batch[0].source) : await call(buildNumberedPayload(batch));
+            segments = parseNumberedTranslation(result, batch.length);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (!incomplete(error) || batch.length === 1)
+                throw error;
+            segments = null;
+        }
+        for (const [index, unit] of batch.entries()) {
+            signal.throwIfAborted();
+            const candidate = segments?.[index] ?? await callUnit(unit.source);
+            output[unit.index] = await finalize(unit, candidate);
+        }
+    }
+    signal.throwIfAborted();
+    return paragraphs.map((_, paragraph) => units
+        .filter(unit => unit.paragraph === paragraph)
+        .map(unit => output[unit.index]).join(gap)).join('\n\n');
+}
+//# sourceMappingURL=pipeline.js.map

package/lib/translation/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/translation/pipeline.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAA;AACpG,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAoB,MAAM,WAAW,CAAA;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAErD,uFAAuF;AACvF,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,MAAM,SAAS,GAA2B,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;IAC3H,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SAChD,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;SACpD,OAAO,CAAC,mDAAmD,EAAE,CAAC,IAAI,EAAE,IAAY,EAAE,IAAY,EAAE,EAAE,CACjG,8CAA8C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;SACrF,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;AACtC,CAAC;AASD,SAAS,OAAO,CAAC,IAAY,EAAE,MAAqB;IAClD,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC/C,OAAO,KAAK,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1G,CAAC;AAED,qFAAqF;AACrF,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,MAAM,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;AACnH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAa,EACb,MAAc,EACd,SAA4C,EAC5C,MAAmB;IAEnB,uFAAuF;IACvF,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAA;IACtC,MAAM,UAAU,GAAG,0BAA0B,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAChH,MAAM,KAAK,GAAW,EAAE,CAAA;IACxB,KAAK,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QACrD,KAAK,MAAM,QAAQ,IAAI,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;YAClD,KAAK,MAAM,MAAM,IAAI,sBAAsB,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM;oBACjD,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAA;YAChF,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,KAAK,CAAS,KAAK,CAAC,MAAM,CAAC,CAAA;IAC9C,MAAM,IAAI,GAAG,KAAK,EAAE,MAAc,EAAmB,EAAE;QACrD,MAAM,CAAC,cAAc,EAAE,CAAA;QACvB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,CAAA;QACtC,MAAM,CAAC,cAAc,EAAE,CAAA;QACvB,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IACD,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAA;IAClD,MAAM,UAAU,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,KAAK,YAAY,KAAK;WACjE,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,wBAAwB,CAAA;IAC/D,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAc,EAAE,KAAK,GAAG,CAAC,EAAmB,EAAE;QACpE,IAAI,CAAC;YAAC,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,CAAA;QAAC,CAAC;QACjC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,CAAC,cAAc,EAAE,CAAA;YACvB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE;gBAAE,MAAM,KAAK,CAAA;YACvE,MAAM,KAAK,GAAa,EAAE,CAAA;YAC1B,KAAK,MAAM,IAAI,IAAI,sBAAsB,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9F,KAAK,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAA;YAC7C,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACxB,CAAC;IACH,CAAC,CAAA;IACD,MAAM,QAAQ,GAAG,KAAK,EAAE,IAAU,EAAE,SAAiB,EAAmB,EAAE;QACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAChD,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAA;QAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAC/D,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QAErC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;QACzF,IAAI,SAAS,GAAG,IAAI,CAAC,MAAM,CAAA;QAC3B,KAAK,MAAM,KAAK,IAAI,OAAO;YAAE,SAAS,GAAG,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;QAC7F,SAAS,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAA;QACrC,KAAK,MAAM,KAAK,IAAI,OAAO;YAAE,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;QAC5G,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAChD,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAA;QAE3C,wEAAwE;QACxE,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;QAC3C,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5C,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,SAAQ;YAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;YAC/D,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;YAC7D,2EAA2E;YAC3E,IAAI,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAA;YACtH,KAAK,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG,UAAU,CAAA;QACrC,CAAC;QACD,MAAM,eAAe,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAC7D,IAAI,eAAe,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAA;QACpH,OAAO,eAAe,CAAA;IACxB,CAAC,CAAA;IACD,yFAAyF;IACzF,KAAK,MAAM,KAAK,IAAI,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,CAAC,cAAc,EAAE,CAAA;QACvB,IAAI,QAAyB,CAAA;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAA;YAC9G,QAAQ,GAAG,wBAAwB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;QAC3D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,cAAc,EAAE,CAAA;YACvB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAA;YACzD,QAAQ,GAAG,IAAI,CAAA;QACjB,CAAC;QACD,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5C,MAAM,CAAC,cAAc,EAAE,CAAA;YACvB,MAAM,SAAS,GAAG,QAAQ,EAAE,CAAC,KAAK,CAAC,IAAI,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YAClE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;QACtD,CAAC;IACH,CAAC;IACD,MAAM,CAAC,cAAc,EAAE,CAAA;IACvB,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,KAAK;SAC1C,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC;SAC5C,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAC5D,CAAC"}

package/lib/translation/preserved-links.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Citation, cross-reference, and link tokens that machine translation drops
+ * or rewrites. Callers mask them before the request and, after restore, use
+ * the same spans to put click targets back on the translated text.
+ */
+export type PreservedLinkKind = "markdown" | "url" | "citation" | "ref";
+export type PreservedLinkSpan = {
+    kind: PreservedLinkKind;
+    start: number;
+    end: number;
+    text: string;
+    /** Markdown or bare URL target. Citation and ref spans leave this empty. */
+    url?: string;
+};
+/**
+ * Drop sentence punctuation glued to a URL. A `)` stays when it closes a
+ * parenthesis that belongs to the URL (`Function_(mathematics)`); it is
+ * removed only when the slice has more closing parens than opening ones.
+ */
+export declare function trimPreservedUrl(raw: string): string;
+/**
+ * Non-overlapping link-like spans in reading order. Longer matches win when
+ * two patterns cover the same characters, so a Markdown link is not also
+ * reported as a bare URL.
+ */
+export declare function findPreservedLinkSpans(text: string): PreservedLinkSpan[];

package/lib/translation/preserved-links.js

@@ -0,0 +1,127 @@
+// Ported from motif (Copyright (c) 2026 poco-ai, MIT). See MOTIF-LICENSE.txt.
+/**
+ * Citation, cross-reference, and link tokens that machine translation drops
+ * or rewrites. Callers mask them before the request and, after restore, use
+ * the same spans to put click targets back on the translated text.
+ */
+const MARKDOWN_LINK = /\[([^\]\n]{1,240})\]\((https?:\/\/[^\s<>\]]+)\)/gi;
+const URL_LINK = /https?:\/\/[^\s、，。<>\]]+/gi;
+/**
+ * Drop sentence punctuation glued to a URL. A `)` stays when it closes a
+ * parenthesis that belongs to the URL (`Function_(mathematics)`); it is
+ * removed only when the slice has more closing parens than opening ones.
+ */
+export function trimPreservedUrl(raw) {
+    let end = raw.length;
+    while (end > 0) {
+        const ch = raw[end - 1];
+        if (ch && /[.,;:!?]/.test(ch)) {
+            end--;
+            continue;
+        }
+        if (ch === ")" && parenBalance(raw.slice(0, end)) < 0) {
+            end--;
+            continue;
+        }
+        break;
+    }
+    return raw.slice(0, end);
+}
+/** Opening parens minus closing parens. Negative means a prose `)` is left over. */
+function parenBalance(text) {
+    let balance = 0;
+    for (const ch of text) {
+        if (ch === "(")
+            balance++;
+        else if (ch === ")")
+            balance--;
+    }
+    return balance;
+}
+const CITATION_LINK = /[[［]\s*[0-9]+[a-z]?(?:\s*[-–—~,，]\s*[0-9]+[a-z]?)*\s*[\]］]/gi;
+const REF_LINK = /\b(?:Figures?|Figs?\.|Tables?|Tabs?\.|Sections?|Secs?\.|Equations?|Eqs?\.|Eqn?\.|Algorithms?|Algs?\.|Theorems?|Lemmas?|Appendices|Appendix)\s+\(?\d+(?:\.\d+)?[a-z]?(?:\s*[-–—]\s*\(?\d+(?:\.\d+)?[a-z]?)?\)?/gi;
+const AUTHOR_NAME = "(?:[A-Z][A-Za-z'’-]{1,40}|[\\u4e00-\\u9fff]{1,12})";
+// PDF text often pads the parenthesis and the comma. Machine translation
+// then rewrites them to fullwidth brackets, a Chinese comma, and 等人.
+const AUTHOR_TAIL = "(?:\\s*et\\s+al\\.?|\\s*(?:and|&)\\s+[A-Z][A-Za-z'’-]{1,40}|等人|等)?";
+const AUTHOR_CITE = `${AUTHOR_NAME}${AUTHOR_TAIL}\\s*[,，]\\s*\\d{4}[a-z]?(?:\\s*年)?`;
+const AUTHOR_YEAR = new RegExp(`[(（]\\s*${AUTHOR_CITE}(?:\\s*[;；]\\s*${AUTHOR_CITE})*\\s*[)）]`, "g");
+function isBatchMarker(text, start, end) {
+    return text[start - 1] === "[" && text[end] === "]";
+}
+function pushMatches(text, pattern, kind, spans, accept) {
+    const flags = pattern.flags.includes("g")
+        ? pattern.flags
+        : `${pattern.flags}g`;
+    const re = new RegExp(pattern.source, flags);
+    for (const match of text.matchAll(re)) {
+        const start = match.index ?? 0;
+        const span = accept
+            ? accept(match)
+            : { kind, start, end: start + match[0].length, text: match[0] };
+        if (!span || span.end <= span.start)
+            continue;
+        if (kind === "citation" && isBatchMarker(text, span.start, span.end)) {
+            continue;
+        }
+        spans.push(span);
+    }
+}
+/**
+ * Non-overlapping link-like spans in reading order. Longer matches win when
+ * two patterns cover the same characters, so a Markdown link is not also
+ * reported as a bare URL.
+ */
+export function findPreservedLinkSpans(text) {
+    if (!text)
+        return [];
+    const found = [];
+    pushMatches(text, MARKDOWN_LINK, "markdown", found, (match) => {
+        const start = match.index ?? 0;
+        let url = match[2] ?? "";
+        let end = start + match[0].length;
+        // The markdown closer can be a `)` that belongs to the URL. Pull those
+        // back in until the URL's parentheses balance.
+        while (parenBalance(url) > 0 && text[end] === ")") {
+            url += ")";
+            end += 1;
+        }
+        url = trimPreservedUrl(url);
+        if (!url)
+            return null;
+        return {
+            kind: "markdown",
+            start,
+            end,
+            text: text.slice(start, end),
+            url,
+        };
+    });
+    pushMatches(text, URL_LINK, "url", found, (match) => {
+        const start = match.index ?? 0;
+        const trimmed = trimPreservedUrl(match[0]);
+        if (!trimmed)
+            return null;
+        return {
+            kind: "url",
+            start,
+            end: start + trimmed.length,
+            text: trimmed,
+            url: trimmed,
+        };
+    });
+    pushMatches(text, CITATION_LINK, "citation", found);
+    pushMatches(text, REF_LINK, "ref", found);
+    pushMatches(text, AUTHOR_YEAR, "citation", found);
+    found.sort((a, b) => a.start - b.start || b.end - a.end);
+    const kept = [];
+    let cursor = 0;
+    for (const span of found) {
+        if (span.start < cursor)
+            continue;
+        kept.push(span);
+        cursor = span.end;
+    }
+    return kept;
+}
+//# sourceMappingURL=preserved-links.js.map

package/lib/translation/preserved-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preserved-links.js","sourceRoot":"","sources":["../../src/translation/preserved-links.ts"],"names":[],"mappings":"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"}

package/lib/translation/prompt.d.ts

@@ -0,0 +1,99 @@
+/**
+ * LLM translation prompts for the Agent path and the OpenAI-compatible Host
+ * path (`crates/agentero-core/.../openai_compatible.rs`). Keep the two in sync.
+ *
+ * The model sees a translation engine, not a chat assistant:
+ * - system: engine rules that always apply, plus academic style (or a
+ *   substantial custom system), plus a short-selection ban when needed
+ * - user: the source text only, wrapped in `"""…"""` unless a custom user
+ *   template contains `{{text}}`
+ *
+ * A one-line colloquial custom prompt is an additional preference. It does
+ * not replace the engine rules.
+ */
+/** Names of `{{…}}` tokens that are not targetLang / sourceLang / text. */
+export declare function unknownTranslatePlaceholders(template: string): string[];
+/** Drop `{{…}}` tokens other than the three recognized placeholders. */
+export declare function stripUnknownTranslatePlaceholders(template: string): string;
+/** True when the template has a `{{text}}` placeholder (inner space allowed). */
+export declare function translateTemplateHasText(template: string): boolean;
+/**
+ * Replace every `{{text}}` with `text`. A function replacement so `$` in the
+ * source is not treated as a replacement pattern.
+ */
+export declare function fillTranslateTextPlaceholder(template: string, text: string): string;
+export type TranslateTemplateIssue = {
+    kind: "unknown";
+    names: string[];
+} | {
+    kind: "missingText";
+};
+/** System box: unknown placeholders fail. Empty is the built-in style. */
+export declare function translateSystemTemplateIssue(template: string): TranslateTemplateIssue | null;
+/**
+ * User box: empty keeps the quoted source. A non-empty template must include
+ * `{{text}}` and only the known placeholders.
+ */
+export declare function translateUserTemplateIssue(template: string): TranslateTemplateIssue | null;
+/**
+ * Academic style block seeded by Settings → 翻译 → 翻译提示词.
+ * A substantial custom system replaces this block only. Engine rules
+ * (output-only, no clarification, preserved math / citations / `[[n]]`)
+ * stay in effect either way.
+ */
+export declare const DEFAULT_TRANSLATE_PROMPT_TEMPLATE = "The source is prose from a research paper, often extracted from a PDF text layer. Translate the meaning, not the word order: write natural, fluent {{targetLang}} the way a researcher in the field would. Re-order clauses and split long sentences when that reads better.\nUse the established {{targetLang}} term for each concept and stay consistent. On a term's first occurrence you may follow it with the original in parentheses, e.g. \u6CE8\u610F\u529B\u673A\u5236\uFF08attention\uFF09.\n\nExamples (return only the translation, this brief):\n- attention \u2192 \u6CE8\u610F\u529B\n- We propose a transformer architecture for sequence transduction. \u2192 \u6211\u4EEC\u63D0\u51FA\u4E00\u79CD\u7528\u4E8E\u5E8F\u5217\u8F6C\u6362\u7684 Transformer \u67B6\u6784\u3002\n- \u5B9E\u9A8C\u8868\u660E\u8BE5\u65B9\u6CD5\u5728 ImageNet \u4E0A\u4F18\u4E8E\u57FA\u7EBF\u3002 \u2192 Experiments show that the method outperforms the baseline on ImageNet.";
+/** True when `text` is a numbered batch payload (`[[1]] …`, `[[2]] …`). */
+export declare function hasNumberedMarkers(text: string): boolean;
+/**
+ * One line, no placeholders, at most 180 characters: a spoken preference
+ * ("翻译得自然一点", "Be terse."). It must not replace the engine rules.
+ */
+export declare function isShortColloquialPrompt(text: string): boolean;
+/**
+ * Word / short phrase vs prose. Mirrors Easydict's dictionary-vs-translation
+ * split with a small phrase allowance: one to four whitespace-separated
+ * tokens, or a Han string of at most eight characters, and no sentence
+ * punctuation. Numbered batches stay prose so layout translation is unchanged.
+ */
+export declare function classifyTranslateQuery(text: string): "word" | "prose";
+/**
+ * Substitute `{{targetLang}}` / `{{sourceLang}}`. Unknown `{{…}}` tokens are
+ * removed. `{{text}}` is left for the user template to fill.
+ */
+export declare function renderTranslatePromptTemplate(template: string, targetLangName: string, sourceLangName?: string): string;
+export type TranslatePromptInput = {
+    text: string;
+    targetLangName: string;
+    /** Display name. Omitted on the Agent path, which always auto-detects. */
+    sourceLangName?: string;
+    page?: number;
+    surface?: string;
+    /**
+     * Legacy single template. Used when `customSystem` is empty.
+     * A short one-line value is a preference; a longer value replaces the
+     * academic style block only.
+     */
+    customPrompt?: string;
+    /** Settings `translate.customSystem`. Wins over `customPrompt`. */
+    customSystem?: string;
+    /**
+     * Settings `translate.customUser`. Applied only when it contains
+     * `{{text}}` (inner whitespace allowed). Otherwise the source is still
+     * sent quoted, and this text is kept as an additional preference.
+     */
+    customUser?: string;
+};
+export type TranslateMessages = {
+    system: string;
+    user: string;
+};
+/**
+ * `(system, user)` pair for an OpenAI-compatible chat completion.
+ * Agent `runOnce` has a single string; use {@link buildTranslatePrompt}.
+ */
+export declare function buildTranslateMessages(opts: TranslatePromptInput): TranslateMessages;
+/**
+ * Single string for ACP `runOnce`. System rules come first, then the source.
+ * The Host translate envelope must not prefix this with "User request:".
+ */
+export declare function buildTranslatePrompt(opts: TranslatePromptInput): string;