md-zh-translation-skill 1.2.3 → 1.4.0

package/dist/src/anchor-normalization.d.ts

@@ -0,0 +1,11 @@
+import type { PromptSlice } from "./translation-state.js";
+export type PromptAnchor = PromptSlice["requiredAnchors"][number];
+type AnchorLike = Pick<PromptAnchor, "english" | "chineseHint">;
+export declare function coalesceRequiredAnchors(requiredAnchors: readonly PromptAnchor[]): PromptAnchor[];
+export declare function formatAnchorDisplay(anchor: AnchorLike): string;
+export declare function normalizeSegmentAnchorText(text: string, slice: PromptSlice | null): string;
+export declare function normalizeSourceSurfaceAnchorText(source: string, text: string, slice: PromptSlice | null): string;
+export declare function injectPlannedAnchorText(source: string, text: string, slice: PromptSlice | null): string;
+export declare function normalizeHeadingLikeAnchorText(source: string, text: string, slice: PromptSlice | null): string;
+export declare function normalizeExplicitRepairAnchorText(source: string, text: string, slice: PromptSlice | null): string;
+export {};

package/dist/src/anchor-normalization.js

@@ -0,0 +1,558 @@
+export function coalesceRequiredAnchors(requiredAnchors) {
+    return requiredAnchors.filter((anchor) => !isShadowedByLongerAnchor(anchor, requiredAnchors));
+}
+export function formatAnchorDisplay(anchor) {
+    return resolveAnchorDisplay(anchor).canonical;
+}
+export function normalizeSegmentAnchorText(text, slice) {
+    if (!slice) {
+        return text;
+    }
+    let normalized = text;
+    const requiredIds = new Set(slice.requiredAnchors.map((anchor) => anchor.anchorId));
+    const repeatIds = new Set([
+        ...slice.repeatAnchors.map((anchor) => anchor.anchorId),
+        ...slice.establishedAnchors.map((anchor) => anchor.anchorId)
+    ]);
+    const anchors = dedupePromptAnchors([
+        ...slice.requiredAnchors,
+        ...slice.repeatAnchors,
+        ...slice.establishedAnchors
+    ]).sort((left, right) => right.english.length - left.english.length);
+    for (const anchor of anchors) {
+        normalized = normalizeSingleAnchor(normalized, anchor, requiredIds.has(anchor.anchorId), repeatIds.has(anchor.anchorId));
+    }
+    return normalizeRepeatedEnglishParenthesesWithLocalHints(normalized);
+}
+export function normalizeSourceSurfaceAnchorText(source, text, slice) {
+    if (!slice) {
+        return text;
+    }
+    const anchors = dedupePromptAnchors([
+        ...slice.requiredAnchors,
+        ...slice.repeatAnchors,
+        ...slice.establishedAnchors
+    ]);
+    if (anchors.length === 0) {
+        return text;
+    }
+    const sourceLines = source.split(/\r?\n/);
+    const translatedLines = text.split(/\r?\n/);
+    let changed = false;
+    for (let index = 0; index < Math.min(sourceLines.length, translatedLines.length); index += 1) {
+        const sourceLine = sourceLines[index] ?? "";
+        let translatedLine = translatedLines[index] ?? "";
+        const sourceAnchors = coalesceSourceLineAnchors(anchors.filter((anchor) => containsWholePhrase(sourceLine, anchor.english)));
+        if (sourceAnchors.length === 0) {
+            continue;
+        }
+        for (const sourceAnchor of sourceAnchors) {
+            const siblingVariants = anchors.filter((candidate) => candidate.familyId === sourceAnchor.familyId &&
+                candidate.anchorId !== sourceAnchor.anchorId &&
+                !containsWholePhrase(sourceLine, candidate.english));
+            for (const variant of siblingVariants) {
+                const normalizedLine = collapseUnexpectedFamilyVariant(translatedLine, variant, sourceAnchor);
+                if (normalizedLine !== translatedLine) {
+                    translatedLine = normalizedLine;
+                    changed = true;
+                }
+            }
+        }
+        translatedLines[index] = translatedLine;
+    }
+    return changed ? translatedLines.join("\n") : text;
+}
+export function injectPlannedAnchorText(source, text, slice) {
+    if (!slice) {
+        return text;
+    }
+    const requiredAnchors = coalesceRequiredAnchors(dedupePromptAnchors(slice.requiredAnchors)).sort((left, right) => right.english.length - left.english.length);
+    if (requiredAnchors.length === 0) {
+        return text;
+    }
+    const sourceLines = source.split(/\r?\n/);
+    const translatedLines = text.split(/\r?\n/);
+    let changed = false;
+    for (let index = 0; index < Math.min(sourceLines.length, translatedLines.length); index += 1) {
+        const sourceLine = sourceLines[index] ?? "";
+        let translatedLine = translatedLines[index] ?? "";
+        const lineAnchors = coalesceSourceLineAnchors(requiredAnchors.filter((anchor) => containsWholePhrase(sourceLine, anchor.english)));
+        for (const anchor of lineAnchors) {
+            if (shouldSkipAnchorInjectionForCommandPhrase(sourceLine, anchor)) {
+                continue;
+            }
+            const injectedLine = injectAnchorIntoLine(translatedLine, anchor);
+            if (injectedLine !== translatedLine) {
+                translatedLine = injectedLine;
+                changed = true;
+            }
+        }
+        translatedLines[index] = translatedLine;
+    }
+    return changed ? translatedLines.join("\n") : text;
+}
+export function normalizeHeadingLikeAnchorText(source, text, slice) {
+    if (!slice) {
+        return text;
+    }
+    const requiredAnchors = dedupePromptAnchors(slice.requiredAnchors).sort((left, right) => right.english.length - left.english.length);
+    if (requiredAnchors.length === 0) {
+        return text;
+    }
+    const sourceHeadingLines = extractHeadingLikeLines(source);
+    const translatedHeadingLines = extractHeadingLikeLines(text);
+    if (sourceHeadingLines.length === 0 || translatedHeadingLines.length === 0) {
+        return text;
+    }
+    let normalized = text;
+    for (let index = 0; index < Math.min(sourceHeadingLines.length, translatedHeadingLines.length); index += 1) {
+        const sourceLine = sourceHeadingLines[index];
+        const translatedLine = translatedHeadingLines[index];
+        const lineAnchors = coalesceSourceLineAnchors(requiredAnchors.filter((anchor) => containsWholePhrase(sourceLine.content, anchor.english)));
+        let normalizedLine = translatedLine.raw;
+        for (const anchor of lineAnchors) {
+            if (!anchor.chineseHint ||
+                anchor.chineseHint.toLowerCase() === anchor.english.toLowerCase() ||
+                !normalizedLine.includes(anchor.chineseHint) ||
+                containsWholePhrase(normalizedLine, anchor.english)) {
+                continue;
+            }
+            normalizedLine = normalizedLine.replace(anchor.chineseHint, `${anchor.chineseHint}（${anchor.english}）`);
+        }
+        if (normalizedLine !== translatedLine.raw) {
+            normalized = normalized.replace(translatedLine.raw, normalizedLine);
+        }
+    }
+    return normalized;
+}
+export function normalizeExplicitRepairAnchorText(source, text, slice) {
+    if (!slice || slice.pendingRepairs.length === 0) {
+        return text;
+    }
+    const targets = slice.pendingRepairs
+        .map((repair) => parseExplicitRepairTarget(repair.instruction))
+        .filter((target) => target !== null);
+    if (targets.length === 0) {
+        return text;
+    }
+    const sourceLines = source.split(/\r?\n/);
+    const translatedLines = text.split(/\r?\n/);
+    const sourceHeadingLines = extractHeadingLikeLines(source);
+    const translatedHeadingLines = extractHeadingLikeLines(text);
+    let changed = false;
+    for (let index = 0; index < Math.min(sourceLines.length, translatedLines.length); index += 1) {
+        const sourceLine = sourceLines[index] ?? "";
+        let translatedLine = translatedLines[index] ?? "";
+        for (const target of targets) {
+            const sourceHeading = extractHeadingLikeLine(sourceLine);
+            const translatedHeading = extractHeadingLikeLine(translatedLine);
+            const matchingAnchor = resolvePromptAnchorForExplicitRepair(target, slice);
+            const english = matchingAnchor?.english ??
+                target.english ??
+                resolveHeadingEnglishFromSource(target.chineseHint, sourceHeadingLines, translatedHeadingLines);
+            if (!english) {
+                continue;
+            }
+            if (sourceHeading &&
+                translatedHeading &&
+                stripInlineMarkdownMarkers(translatedHeading.content).includes(target.chineseHint)) {
+                const normalizedHeading = matchingAnchor && translatedHeading.content.includes(matchingAnchor.chineseHint)
+                    ? injectAnchorIntoLine(translatedHeading.content, matchingAnchor)
+                    : normalizeHeadingRepairContent(translatedHeading.content, english);
+                if (normalizedHeading !== translatedHeading.content) {
+                    translatedLine = translatedLine.replace(translatedHeading.content, normalizedHeading);
+                    changed = true;
+                    continue;
+                }
+            }
+            if (!containsWholePhrase(sourceLine, english) ||
+                !translatedLine.includes(target.chineseHint) ||
+                containsWholePhrase(translatedLine, english)) {
+                continue;
+            }
+            if (matchingAnchor) {
+                const normalizedLine = injectAnchorIntoLine(translatedLine, matchingAnchor);
+                if (normalizedLine !== translatedLine) {
+                    translatedLine = normalizedLine;
+                    changed = true;
+                    continue;
+                }
+            }
+            translatedLine = translatedLine.replace(target.chineseHint, `${target.chineseHint}（${english}）`);
+            changed = true;
+        }
+        translatedLines[index] = translatedLine;
+    }
+    return changed ? translatedLines.join("\n") : text;
+}
+function resolveHeadingEnglishFromSource(chineseHint, sourceHeadingLines, translatedHeadingLines) {
+    for (let index = 0; index < Math.min(sourceHeadingLines.length, translatedHeadingLines.length); index += 1) {
+        const sourceHeading = sourceHeadingLines[index];
+        const translatedHeading = translatedHeadingLines[index];
+        if (!sourceHeading || !translatedHeading) {
+            continue;
+        }
+        if (stripInlineMarkdownMarkers(translatedHeading.content).trim() === chineseHint &&
+            /[A-Za-z]/.test(sourceHeading.content)) {
+            return sourceHeading.content.trim();
+        }
+    }
+    return null;
+}
+function normalizeHeadingRepairContent(content, english) {
+    if (!english || containsWholePhrase(content, english)) {
+        return content;
+    }
+    const parentheticalMatch = content.match(/（([^）]*[A-Za-z][^）]*)）(?!.*（)/);
+    if (!parentheticalMatch?.[1]) {
+        return `${content}（${english}）`;
+    }
+    const inner = parentheticalMatch[1].trim();
+    if (containsWholePhrase(inner, english)) {
+        return content;
+    }
+    return content.replace(parentheticalMatch[0], `（${inner}，${english}）`);
+}
+function resolvePromptAnchorForExplicitRepair(target, slice) {
+    const targetEnglish = target.english?.toLowerCase();
+    if (!targetEnglish) {
+        return null;
+    }
+    const anchors = dedupePromptAnchors([
+        ...slice.requiredAnchors,
+        ...slice.repeatAnchors,
+        ...slice.establishedAnchors
+    ]);
+    return (anchors.find((anchor) => anchor.english.toLowerCase() === targetEnglish &&
+        anchor.chineseHint !== target.english &&
+        target.chineseHint.includes(anchor.chineseHint)) ?? null);
+}
+function normalizeSingleAnchor(text, anchor, isRequired, isRepeatOrEstablished) {
+    const display = resolveAnchorDisplay(anchor);
+    const english = display.english;
+    const chineseHint = display.chineseDisplay;
+    if (!english) {
+        return text;
+    }
+    const escapedEnglish = escapeRegExp(english);
+    let normalized = text;
+    if (display.mode === "chinese-primary") {
+        const escapedChinese = escapeRegExp(chineseHint);
+        const canonical = display.canonical;
+        normalized = normalized.replace(new RegExp(`${escapedEnglish}（${escapedChinese}）`, "g"), canonical);
+        normalized = normalized.replace(new RegExp(`${escapedEnglish}（${escapedEnglish}）`, "g"), canonical);
+        normalized = normalized.replace(new RegExp(`${escapedChinese}（${escapedEnglish}）\\s*（${escapedEnglish}）`, "g"), canonical);
+        normalized = normalized.replace(new RegExp(`${escapedChinese}（${escapedChinese}）`, "g"), canonical);
+        if (isRepeatOrEstablished) {
+            normalized = normalized.replace(new RegExp(`${escapedChinese}（${escapedEnglish}）`, "g"), chineseHint);
+        }
+        return normalized;
+    }
+    if (display.mode === "english-primary") {
+        const escapedChinese = escapeRegExp(chineseHint);
+        const canonical = display.canonical;
+        normalized = normalized.replace(new RegExp(`${escapedEnglish}（${escapedChinese}\\s+${escapedEnglish}）`, "g"), canonical);
+        normalized = normalized.replace(new RegExp(`${escapedEnglish}\\s*${escapedChinese}（${escapedEnglish}）`, "g"), canonical);
+        normalized = normalized.replace(new RegExp(`${escapedChinese}（${escapedEnglish}）`, "g"), canonical);
+        normalized = normalized.replace(new RegExp(`${escapedEnglish}（${escapedEnglish}）`, "g"), canonical);
+        if (isRepeatOrEstablished) {
+            normalized = normalized.replace(new RegExp(`${escapedEnglish}（${escapedChinese}）`, "g"), english);
+        }
+        return normalized;
+    }
+    normalized = normalized.replace(new RegExp(`${escapedEnglish}（${escapedEnglish}）`, "g"), english);
+    if (isRequired) {
+        normalized = collapseRepeatedEnglishParentheses(normalized, english);
+    }
+    return normalized;
+}
+function collapseRepeatedEnglishParentheses(text, english) {
+    const escapedEnglish = escapeRegExp(english);
+    return text.replace(new RegExp(`（${escapedEnglish}）\\s*（${escapedEnglish}）`, "g"), `（${english}）`);
+}
+function injectAnchorIntoLine(text, anchor) {
+    const display = resolveAnchorDisplay(anchor);
+    if (!display.english || display.mode === "english-only") {
+        return text;
+    }
+    if (display.mode === "english-primary") {
+        if (text.includes(display.canonical)) {
+            return text;
+        }
+        if (containsWholePhrase(text, display.english) && !text.includes(display.chineseDisplay)) {
+            return replaceWholePhraseOnce(text, display.english, display.canonical);
+        }
+        if (text.includes(anchor.chineseHint)) {
+            return replaceFirst(text, anchor.chineseHint, display.canonical);
+        }
+        if (display.chineseDisplay && text.includes(display.chineseDisplay)) {
+            return replaceFirst(text, display.chineseDisplay, display.canonical);
+        }
+        return text;
+    }
+    if (text.includes(display.canonical) || containsWholePhrase(text, display.english)) {
+        return text;
+    }
+    if (text.includes(display.chineseDisplay)) {
+        return replaceFirst(text, display.chineseDisplay, display.canonical);
+    }
+    if (text.includes(anchor.chineseHint)) {
+        return replaceFirst(text, anchor.chineseHint, display.canonical);
+    }
+    return text;
+}
+function collapseUnexpectedFamilyVariant(text, variant, sourceAnchor) {
+    const variantDisplay = resolveAnchorDisplay(variant);
+    const sourceDisplay = resolveAnchorDisplay(sourceAnchor);
+    let normalized = text;
+    const variantSuffix = variant.english.startsWith(`${sourceAnchor.english} `)
+        ? variant.english.slice(sourceAnchor.english.length).trim()
+        : "";
+    const replacements = [
+        [variantDisplay.canonical, sourceDisplay.canonical],
+        [`${variant.english}（${sourceAnchor.english}）`, sourceDisplay.canonical],
+        [`${variant.english}（${sourceDisplay.chineseDisplay}）`, sourceDisplay.canonical],
+        [`${variantDisplay.canonical}（${sourceAnchor.english}）`, sourceDisplay.canonical],
+        [`${sourceDisplay.canonical}（${sourceAnchor.english}）`, sourceDisplay.canonical]
+    ];
+    if (variantSuffix) {
+        replacements.push([`${sourceDisplay.canonical} ${variantSuffix}（${sourceAnchor.english}）`, sourceDisplay.canonical], [`${sourceDisplay.canonical} ${variantSuffix}`, sourceDisplay.canonical]);
+    }
+    for (const [from, to] of replacements) {
+        if (from && to && normalized.includes(from)) {
+            normalized = normalized.split(from).join(to);
+        }
+    }
+    if (containsWholePhrase(normalized, variant.english) && !containsWholePhrase(text, sourceAnchor.english)) {
+        normalized = replaceWholePhraseOnce(normalized, variant.english, sourceDisplay.canonical);
+    }
+    return normalized;
+}
+function coalesceSourceLineAnchors(anchors) {
+    return anchors.filter((anchor) => !anchors.some((candidate) => candidate.anchorId !== anchor.anchorId &&
+        candidate.familyId === anchor.familyId &&
+        candidate.english.length > anchor.english.length &&
+        containsWholePhrase(candidate.english, anchor.english)));
+}
+function shouldSkipAnchorInjectionForCommandPhrase(sourceLine, anchor) {
+    const trimmed = sourceLine.trim();
+    const bulletMatch = trimmed.match(/^(?:[-*+]|\d+[.)])\s+(.+)$/);
+    const body = bulletMatch?.[1]?.trim();
+    if (!body) {
+        return false;
+    }
+    const english = anchor.english.trim();
+    if (!english || /\s/.test(english)) {
+        return false;
+    }
+    const withoutTrailingExplanation = body.replace(/\s*\([^)]*\)\s*$/, "").trim();
+    const leadingToken = withoutTrailingExplanation.match(/^([A-Za-z][A-Za-z0-9+._/-]*)\b/)?.[1]?.trim();
+    if (!leadingToken || leadingToken.toLowerCase() !== english.toLowerCase()) {
+        return false;
+    }
+    const remainder = withoutTrailingExplanation.slice(leadingToken.length).trim();
+    if (!remainder) {
+        return false;
+    }
+    if (remainder.includes(",")) {
+        return true;
+    }
+    return /^[A-Za-z0-9./_-]/.test(remainder);
+}
+function extractHeadingLikeLine(rawLine) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const atxMatch = trimmed.match(/^#{1,6}[ \t]+(.+?)(?:[ \t]+#+)?$/);
+    if (atxMatch?.[1]) {
+        return { raw: rawLine, content: atxMatch[1].trim() };
+    }
+    const boldMatch = trimmed.match(/^\*\*(.+)\*\*$/);
+    if (boldMatch?.[1]) {
+        return { raw: rawLine, content: boldMatch[1].trim() };
+    }
+    return null;
+}
+function parseExplicitRepairTarget(instruction) {
+    const match = instruction.match(/需补为“([^（”]+)（([^）]+)）”/);
+    if (match?.[1] && match[2]) {
+        return {
+            chineseHint: match[1].trim(),
+            english: match[2].trim()
+        };
+    }
+    const english = instruction.match(/关键术语“([^”]*[A-Za-z][^”]*)”/)?.[1]?.trim() ??
+        instruction.match(/首现术语\s+([A-Za-z][A-Za-z0-9 .+/_-]*)\s+未补/)?.[1]?.trim() ??
+        instruction.match(/[：:]\s*([A-Za-z][A-Za-z0-9 .+/_-]*)\s+首次出现需补/)?.[1]?.trim() ??
+        instruction.match(/括注“([^”]*[A-Za-z][^”]*)”/)?.[1]?.trim() ??
+        instruction.match(/“([^”]*[A-Za-z][^”]*)”缺少/)?.[1]?.trim() ??
+        null;
+    const locationText = instruction.match(/位置：[^。；\n“]*“([^”]+)”/)?.[1]?.trim() ??
+        instruction.match(/位置：(.+?)。问题[:：]/)?.[1]?.trim() ??
+        instruction.match(/`([^`]+)`/)?.[1]?.trim() ??
+        null;
+    const chineseHint = locationText ? stripHeadingMarkers(stripInlineMarkdownMarkers(locationText).trim()) : null;
+    if (!chineseHint) {
+        return null;
+    }
+    return { chineseHint, english };
+}
+function stripInlineMarkdownMarkers(text) {
+    return text.replace(/[*_`~]/g, "");
+}
+function stripHeadingMarkers(text) {
+    return text.replace(/^#{1,6}\s+/, "").trim();
+}
+function extractHeadingLikeLines(text) {
+    const headings = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const heading = extractHeadingLikeLine(rawLine);
+        if (heading) {
+            headings.push(heading);
+        }
+    }
+    return headings;
+}
+function dedupePromptAnchors(anchors) {
+    const seen = new Set();
+    const deduped = [];
+    for (const anchor of anchors) {
+        if (seen.has(anchor.anchorId)) {
+            continue;
+        }
+        seen.add(anchor.anchorId);
+        deduped.push(anchor);
+    }
+    return deduped;
+}
+function isShadowedByLongerAnchor(anchor, anchors) {
+    const english = normalizeAnchorText(anchor.english);
+    const chineseHint = normalizeAnchorText(anchor.chineseHint);
+    if (!english || english !== chineseHint) {
+        return false;
+    }
+    return anchors.some((candidate) => {
+        if (candidate.anchorId === anchor.anchorId) {
+            return false;
+        }
+        const candidateEnglish = normalizeAnchorText(candidate.english);
+        if (!candidateEnglish || candidateEnglish.length <= english.length) {
+            return false;
+        }
+        return containsWholeEnglishPhrase(candidateEnglish, english);
+    });
+}
+function containsWholeEnglishPhrase(haystack, needle) {
+    const escapedNeedle = escapeRegExp(needle);
+    return new RegExp(`\\b${escapedNeedle}\\b`, "i").test(haystack);
+}
+function containsWholePhrase(haystack, needle) {
+    if (/[A-Za-z]/.test(needle)) {
+        return containsWholeEnglishPhrase(haystack, needle);
+    }
+    return haystack.includes(needle);
+}
+function normalizeAnchorText(value) {
+    return value.trim().toLowerCase();
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function replaceFirst(text, needle, replacement) {
+    const index = text.indexOf(needle);
+    if (index === -1) {
+        return text;
+    }
+    return `${text.slice(0, index)}${replacement}${text.slice(index + needle.length)}`;
+}
+function replaceWholePhraseOnce(text, needle, replacement) {
+    if (!/[A-Za-z]/.test(needle)) {
+        return replaceFirst(text, needle, replacement);
+    }
+    const pattern = new RegExp(`\\b${escapeRegExp(needle)}\\b`);
+    return text.replace(pattern, replacement);
+}
+function normalizeRepeatedEnglishParenthesesWithLocalHints(text) {
+    const localEnglishPrimary = new Map();
+    const englishPrimaryPattern = /\b([A-Za-z][A-Za-z0-9.+/_ -]{1,})（([^（）\n]+)）/g;
+    for (const match of text.matchAll(englishPrimaryPattern)) {
+        const english = match[1]?.trim();
+        const explainer = match[2]?.trim();
+        if (!english || !explainer) {
+            continue;
+        }
+        if (english.toLowerCase() === explainer.toLowerCase()) {
+            continue;
+        }
+        localEnglishPrimary.set(english.toLowerCase(), `${english}（${explainer}）`);
+    }
+    return text.replace(englishPrimaryPattern, (raw, englishRaw, innerRaw) => {
+        const english = String(englishRaw).trim();
+        const inner = String(innerRaw).trim();
+        if (!english || !inner) {
+            return raw;
+        }
+        if (english.toLowerCase() !== inner.toLowerCase()) {
+            return raw;
+        }
+        const canonical = localEnglishPrimary.get(english.toLowerCase());
+        return canonical ?? english;
+    });
+}
+function resolveAnchorDisplay(anchor) {
+    const english = anchor.english.trim();
+    const chineseHint = anchor.chineseHint.trim();
+    if (!english || !chineseHint || chineseHint.toLowerCase() === english.toLowerCase()) {
+        return {
+            mode: "english-only",
+            english,
+            chineseDisplay: "",
+            canonical: english,
+            repeatText: english
+        };
+    }
+    const strippedEnglishPrefix = stripLeadingEnglishHint(chineseHint, english);
+    const strippedEnglishSuffix = stripTrailingEnglishHint(strippedEnglishPrefix ?? chineseHint, english);
+    const chineseDisplay = strippedEnglishSuffix ?? strippedEnglishPrefix ?? chineseHint;
+    if (shouldPreferEnglishPrimary(english, strippedEnglishPrefix)) {
+        return {
+            mode: "english-primary",
+            english,
+            chineseDisplay,
+            canonical: `${english}（${chineseDisplay}）`,
+            repeatText: english
+        };
+    }
+    return {
+        mode: "chinese-primary",
+        english,
+        chineseDisplay,
+        canonical: `${chineseDisplay}（${english}）`,
+        repeatText: chineseDisplay
+    };
+}
+function stripLeadingEnglishHint(chineseHint, english) {
+    if (!chineseHint.toLowerCase().startsWith(english.toLowerCase())) {
+        return null;
+    }
+    const suffix = chineseHint.slice(english.length).trim();
+    return suffix.length > 0 ? suffix : null;
+}
+function stripTrailingEnglishHint(chineseHint, english) {
+    if (!chineseHint.toLowerCase().endsWith(english.toLowerCase())) {
+        return null;
+    }
+    const prefix = chineseHint
+        .slice(0, Math.max(0, chineseHint.length - english.length))
+        .trim()
+        .replace(/[（(：:，,、\-–—\s]+$/u, "")
+        .trim();
+    return prefix.length > 0 ? prefix : null;
+}
+function shouldPreferEnglishPrimary(english, strippedEnglishPrefix) {
+    if (strippedEnglishPrefix) {
+        return true;
+    }
+    return /^[A-Za-z0-9][A-Za-z0-9.+/_-]*$/.test(english);
+}

package/dist/src/internal/prompts/scheme-h.d.ts

@@ -1,9 +1,11 @@
+export declare const DOCUMENT_ANALYSIS_PROMPT: string;
 export declare const INITIAL_TRANSLATION_PROMPT: string;
 export declare const GATE_AUDIT_PROMPT: string;
 export declare const BUNDLED_GATE_AUDIT_PROMPT: string;
 export declare const REPAIR_PROMPT: string;
 export declare const STYLE_POLISH_PROMPT: string;
 export declare function buildInitialPrompt(source: string): string;
+export declare function buildDocumentAnalysisPrompt(document: string): string;
 export declare function buildGateAuditPrompt(source: string, translation: string): string;
 export declare function buildBundledGateAuditPrompt(segments: string): string;
 export declare function buildRepairPrompt(source: string, translation: string, mustFix: readonly string[]): string;

package/dist/src/internal/prompts/scheme-h.js

@@ -6,6 +6,54 @@ Markdown 结构要求：
 4. 不要把代码块、命令行片段或配置键值误译成中文。
 5. 如果原文正文使用了可翻译的 Markdown 强调结构（如 **加粗**、*斜体*）或命令/flag 写法（如 --flag），译文应保持等价结构；不要丢掉强调，也不要把普通命令/flag 误改成代码块、标题或其他 Markdown 结构。
 `.trim();
+export const DOCUMENT_ANALYSIS_PROMPT = `
+你是一名科技与科普翻译编辑的前置分析器。请阅读下面的整篇 Markdown 文档分析输入，并只返回 JSON，不要返回散文说明。
+
+目标：
+1. 找出全文里需要建立“首次中英锚定”的候选专名、产品名、机构名、项目名和关键术语。
+2. 标出它们在全文中的首次出现位置（chunkId + segmentId）。
+3. 将同一概念家族的不同英文变体归并到同一个 familyKey。
+4. 对明显不需要强制双语锚定的通用词，放进 ignoredTerms。
+
+要求：
+1. 只返回 JSON。
+2. anchors 中每一项都必须包含：
+   - english
+   - chineseHint
+   - familyKey
+   - firstOccurrence.chunkId
+   - firstOccurrence.segmentId
+3. english 必须是原文里实际出现的英文形式，不要杜撰。
+4. chineseHint 只写最小必要的中文主译或中文说明，不要写整句。
+5. familyKey 用于归并同一概念家族，保持稳定、简短、可复用。
+6. 只有真正需要首现双语锚定的项才放进 anchors。像 Earth、reptiles、paleontologist 这类通用名词、职业称谓、类群名或常见科学词，通常应放进 ignoredTerms。
+7. 如果同一项在标题、引用、列表项和正文中都出现，首次出现位置必须精确落在最先出现的那个 chunkId / segmentId。
+8. 不要输出重复的 anchors。
+
+返回格式：
+{
+  "anchors": [
+    {
+      "english": "Prompt injection attacks",
+      "chineseHint": "提示注入攻击",
+      "familyKey": "prompt injection attacks",
+      "firstOccurrence": {
+        "chunkId": "chunk-3",
+        "segmentId": "chunk-3-segment-1"
+      }
+    }
+  ],
+  "ignoredTerms": [
+    {
+      "english": "Earth",
+      "reason": "通用名词"
+    }
+  ]
+}
+
+【文档分析输入】
+{{document}}
+`.trim();
 export const INITIAL_TRANSLATION_PROMPT = `
 你是一名科技与科普翻译编辑。请把下面的英文 Markdown 文章翻译成自然、准确、可读性高的中文 Markdown，但本次任务以“硬性项正确”为第一优先级。请严格遵守以下要求：
 
@@ -189,6 +237,9 @@ export const STYLE_POLISH_PROMPT = `
 export function buildInitialPrompt(source) {
     return INITIAL_TRANSLATION_PROMPT.replaceAll("{{source}}", source);
 }
+export function buildDocumentAnalysisPrompt(document) {
+    return DOCUMENT_ANALYSIS_PROMPT.replaceAll("{{document}}", document);
+}
 export function buildGateAuditPrompt(source, translation) {
     return GATE_AUDIT_PROMPT.replaceAll("{{source}}", source).replaceAll("{{translation}}", translation);
 }

package/dist/src/markdown-protection.d.ts

@@ -7,6 +7,7 @@ export type ProtectedSpan = {
     id: string;
     kind: ProtectedKind;
     raw: string;
+    labelText?: string;
 };
 export type ProtectedMarkdown = {
     protectedBody: string;