|
|
@@ -0,0 +1,513 @@
|
|
|
+/**
|
|
|
+ * Pure assembly of the minimal-update briefing for one out-of-sync
|
|
|
+ * translation pair: the authored side's changes since the last confirmed
|
|
|
+ * state at the narrowest safely mapped granularity (code-fence-only splice,
|
|
|
+ * changed Markdown units, heading sections, whole document), the terminology
|
|
|
+ * rows those changes touch, first-occurrence movement notes, and a digest of
|
|
|
+ * the binding update rules. The unit mapping, mechanical code splice, and
|
|
|
+ * first-occurrence tracking adopt the planner mechanics validated in the
|
|
|
+ * incremental-pipeline work (PR #684). The CLI wrapper is
|
|
|
+ * `scripts/gen-translation-brief.ts`; the workflow that consumes the
|
|
|
+ * briefing is `.agents/skills/dsh-translate-docs/SKILL.md`.
|
|
|
+ */
|
|
|
+
|
|
|
+import type { Nodes } from 'mdast'
|
|
|
+import { parseTranslationMarkdown } from './translation-pairing.ts'
|
|
|
+
|
|
|
+/** One block-level span of a Markdown document, in document order. */
|
|
|
+export interface MarkdownSpan {
|
|
|
+ /** Position in the span list; briefing ids derive from it. */
|
|
|
+ index: number
|
|
|
+ /**
|
|
|
+ * Structural kind compared for alignment, language-neutral: container path
|
|
|
+ * plus node type for units (`root.3:tableRow`), depth for sections (`section:2`).
|
|
|
+ */
|
|
|
+ kind: string
|
|
|
+ /** Reader-facing label: heading text for sections, node type for units. */
|
|
|
+ label: string
|
|
|
+ /** 1-based first source line. */
|
|
|
+ startLine: number
|
|
|
+ /** 1-based last source line. */
|
|
|
+ endLine: number
|
|
|
+ /** The span's text, trailing newline normalized to exactly one. */
|
|
|
+ text: string
|
|
|
+}
|
|
|
+
|
|
|
+function linesOf(markdown: string): string[] {
|
|
|
+ const lines = markdown.replaceAll('\r\n', '\n').split('\n')
|
|
|
+ if (lines.at(-1) === '') lines.pop()
|
|
|
+ return lines
|
|
|
+}
|
|
|
+
|
|
|
+function sliceLines(lines: string[], startLine: number, endLine: number): string {
|
|
|
+ return `${lines.slice(startLine - 1, endLine).join('\n')}\n`
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * List a document's translation units: the outermost block nodes a minimal
|
|
|
+ * update can replace independently. Headings, paragraphs, code fences, table
|
|
|
+ * rows, list items, block quotes, HTML blocks, thematic breaks, and link
|
|
|
+ * definitions are units; the container path is part of the kind so kind
|
|
|
+ * sequences only align when container membership also aligns.
|
|
|
+ *
|
|
|
+ * @param markdown - Document text.
|
|
|
+ * @returns Units in document order.
|
|
|
+ */
|
|
|
+export function markdownUnits(markdown: string): MarkdownSpan[] {
|
|
|
+ const positions: Array<{ kind: string; label: string; startLine: number; endLine: number }> = []
|
|
|
+ const visit = (node: Nodes, path: string): void => {
|
|
|
+ let kind: string | undefined
|
|
|
+ switch (node.type) {
|
|
|
+ case 'heading':
|
|
|
+ kind = `${path}:heading:${node.depth}`
|
|
|
+ break
|
|
|
+ case 'paragraph':
|
|
|
+ case 'code':
|
|
|
+ case 'tableRow':
|
|
|
+ case 'listItem':
|
|
|
+ case 'blockquote':
|
|
|
+ case 'html':
|
|
|
+ case 'thematicBreak':
|
|
|
+ case 'definition':
|
|
|
+ kind = `${path}:${node.type}`
|
|
|
+ break
|
|
|
+ default:
|
|
|
+ break
|
|
|
+ }
|
|
|
+ if (kind !== undefined && node.position !== undefined) {
|
|
|
+ positions.push({ kind, label: node.type, startLine: node.position.start.line, endLine: node.position.end.line })
|
|
|
+ return
|
|
|
+ }
|
|
|
+ if ('children' in node) for (const [index, child] of node.children.entries()) visit(child, `${path}.${index}`)
|
|
|
+ }
|
|
|
+ visit(parseTranslationMarkdown(markdown), 'root')
|
|
|
+ positions.sort((left, right) => left.startLine - right.startLine)
|
|
|
+ const lines = linesOf(markdown)
|
|
|
+ return positions.map((position, index) => ({
|
|
|
+ index,
|
|
|
+ ...position,
|
|
|
+ text: sliceLines(lines, position.startLine, position.endLine),
|
|
|
+ }))
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * List a document's heading-delimited sections, including a leading
|
|
|
+ * `preamble` span when content precedes the first heading.
|
|
|
+ *
|
|
|
+ * @param markdown - Document text.
|
|
|
+ * @returns Sections in document order.
|
|
|
+ */
|
|
|
+export function sectionSpans(markdown: string): MarkdownSpan[] {
|
|
|
+ const headings: Array<{ depth: number; line: number; label: string }> = []
|
|
|
+ const visit = (node: Nodes): void => {
|
|
|
+ if (node.type === 'heading' && node.position !== undefined) {
|
|
|
+ let label = ''
|
|
|
+ const collect = (child: Nodes): void => {
|
|
|
+ if ('value' in child && typeof child.value === 'string') label += child.value
|
|
|
+ if ('children' in child) for (const grandchild of child.children) collect(grandchild)
|
|
|
+ }
|
|
|
+ for (const child of node.children) collect(child)
|
|
|
+ headings.push({ depth: node.depth, line: node.position.start.line, label })
|
|
|
+ }
|
|
|
+ if ('children' in node) for (const child of node.children) visit(child)
|
|
|
+ }
|
|
|
+ visit(parseTranslationMarkdown(markdown))
|
|
|
+ headings.sort((left, right) => left.line - right.line)
|
|
|
+ const lines = linesOf(markdown)
|
|
|
+ const spans: MarkdownSpan[] = []
|
|
|
+ const firstHeadingLine = headings[0]?.line ?? lines.length + 1
|
|
|
+ if (firstHeadingLine > 1) {
|
|
|
+ spans.push({ index: 0, kind: 'preamble', label: '(preamble before the first heading)', startLine: 1, endLine: firstHeadingLine - 1, text: sliceLines(lines, 1, firstHeadingLine - 1) })
|
|
|
+ }
|
|
|
+ for (const [order, heading] of headings.entries()) {
|
|
|
+ const endLine = (headings[order + 1]?.line ?? lines.length + 1) - 1
|
|
|
+ spans.push({
|
|
|
+ index: spans.length,
|
|
|
+ // Depth only: heading TEXT is translated across a pair, so it cannot
|
|
|
+ // participate in cross-language alignment.
|
|
|
+ kind: `section:${heading.depth}`,
|
|
|
+ label: heading.label === '' ? '(untitled section)' : heading.label,
|
|
|
+ startLine: heading.line,
|
|
|
+ endLine,
|
|
|
+ text: sliceLines(lines, heading.line, endLine),
|
|
|
+ })
|
|
|
+ }
|
|
|
+ return spans
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Whether two span lists map one to one: same non-zero length and the same
|
|
|
+ * kind at every position.
|
|
|
+ *
|
|
|
+ * @param left - One document's spans.
|
|
|
+ * @param right - The other document's spans.
|
|
|
+ * @returns True when index-wise mapping is sound.
|
|
|
+ */
|
|
|
+export function spansAligned(left: MarkdownSpan[], right: MarkdownSpan[]): boolean {
|
|
|
+ return left.length > 0
|
|
|
+ && left.length === right.length
|
|
|
+ && left.every((span, index) => span.kind === right[index]?.kind)
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Indices whose text differs between two aligned span lists.
|
|
|
+ *
|
|
|
+ * @param before - Spans of the earlier state.
|
|
|
+ * @param after - Spans of the later state, aligned with `before`.
|
|
|
+ * @returns Ascending changed indices.
|
|
|
+ */
|
|
|
+export function changedSpanIndices(before: MarkdownSpan[], after: MarkdownSpan[]): number[] {
|
|
|
+ return before.filter((span, index) => span.text !== after[index]?.text).map(span => span.index)
|
|
|
+}
|
|
|
+
|
|
|
+function codeSpansOf(markdown: string): MarkdownSpan[] {
|
|
|
+ return markdownUnits(markdown).filter(span => span.kind.endsWith(':code'))
|
|
|
+ .map((span, index) => ({ ...span, index }))
|
|
|
+}
|
|
|
+
|
|
|
+function replaceSpanTexts(markdown: string, spans: MarkdownSpan[], replacements: Map<number, string>): string {
|
|
|
+ const lines = linesOf(markdown)
|
|
|
+ for (const [index, replacement] of [...replacements.entries()].sort((left, right) => right[0] - left[0])) {
|
|
|
+ const span = spans[index]
|
|
|
+ if (span === undefined) throw new Error(`translation brief: unknown replacement span ${index}`)
|
|
|
+ lines.splice(span.startLine - 1, span.endLine - span.startLine + 1, ...linesOf(replacement))
|
|
|
+ }
|
|
|
+ return `${lines.join('\n')}\n`
|
|
|
+}
|
|
|
+
|
|
|
+function maskCodeSpans(markdown: string, spans: MarkdownSpan[]): string {
|
|
|
+ return replaceSpanTexts(markdown, spans, new Map(spans.map(span => [span.index, `DSH_TRANSLATION_CODE_${span.index}\n`])))
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Compute the counterpart update for a change confined to fenced code
|
|
|
+ * blocks. Fences are byte-identical across a pair, so when the source's
|
|
|
+ * prose is untouched and the counterpart's fences match the last-confirmed
|
|
|
+ * source, splicing the edited fences into the counterpart is the complete
|
|
|
+ * update — no translation judgment is involved.
|
|
|
+ *
|
|
|
+ * @param confirmedSource - The changed side's last-confirmed text.
|
|
|
+ * @param currentSource - The changed side's current text.
|
|
|
+ * @param counterpart - The other side's current text.
|
|
|
+ * @returns The updated counterpart, or undefined when the change is not code-only.
|
|
|
+ */
|
|
|
+export function computeMechanicalUpdate(confirmedSource: string, currentSource: string, counterpart: string): string | undefined {
|
|
|
+ const confirmed = codeSpansOf(confirmedSource)
|
|
|
+ const current = codeSpansOf(currentSource)
|
|
|
+ const target = codeSpansOf(counterpart)
|
|
|
+ if (confirmed.length === 0 || confirmed.length !== current.length || confirmed.length !== target.length) return undefined
|
|
|
+ if (maskCodeSpans(confirmedSource, confirmed) !== maskCodeSpans(currentSource, current)) return undefined
|
|
|
+ if (confirmed.some((span, index) => span.text !== target[index]?.text)) return undefined
|
|
|
+ const changed = current.filter((span, index) => span.text !== confirmed[index]?.text)
|
|
|
+ if (changed.length === 0) return undefined
|
|
|
+ return replaceSpanTexts(counterpart, target, new Map(changed.map(span => [span.index, span.text])))
|
|
|
+}
|
|
|
+
|
|
|
+/** One parsed terminology-table data row. */
|
|
|
+export interface TerminologyRow {
|
|
|
+ english: string
|
|
|
+ chinese: string
|
|
|
+ /** The 首次出现 cell (first-occurrence rendering), possibly empty. */
|
|
|
+ first: string
|
|
|
+ /** The verbatim table row. */
|
|
|
+ line: string
|
|
|
+}
|
|
|
+
|
|
|
+/** Strip Markdown emphasis and code markers from a terminology cell. */
|
|
|
+function plainTerm(cell: string): string {
|
|
|
+ return cell.replaceAll('`', '').replaceAll('**', '').trim()
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Parse the data rows of the terminology table.
|
|
|
+ *
|
|
|
+ * @param terminology - Full `docs/i18n/terminology.md` contents.
|
|
|
+ * @returns Rows in table order.
|
|
|
+ */
|
|
|
+export function parseTerminologyRows(terminology: string): TerminologyRow[] {
|
|
|
+ const rows: TerminologyRow[] = []
|
|
|
+ for (const line of terminology.split('\n')) {
|
|
|
+ if (!line.startsWith('|')) continue
|
|
|
+ if (/^\|[\s:|-]+\|$/.test(line)) continue
|
|
|
+ const cells = line.split('|').map(cell => cell.trim())
|
|
|
+ const english = plainTerm(cells[1] ?? '')
|
|
|
+ if (english === '' || english === 'English') continue
|
|
|
+ rows.push({ english, chinese: plainTerm(cells[2] ?? ''), first: plainTerm(cells[3] ?? ''), line })
|
|
|
+ }
|
|
|
+ return rows
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Character offsets of a term's occurrences. English word-like terms match
|
|
|
+ * on word boundaries and accept plural inflections (`agents`, `registries`);
|
|
|
+ * other terms match as case-insensitive substrings.
|
|
|
+ *
|
|
|
+ * @param text - Text to search.
|
|
|
+ * @param term - The term to find.
|
|
|
+ * @param englishInflections - Whether to accept English plural forms.
|
|
|
+ * @returns Ascending match offsets.
|
|
|
+ */
|
|
|
+export function termOffsets(text: string, term: string, englishInflections = false): number[] {
|
|
|
+ if (term === '') return []
|
|
|
+ const escape = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
|
|
|
+ const wordLike = /^[A-Za-z0-9][A-Za-z0-9 ._-]*[A-Za-z0-9]$/.test(term)
|
|
|
+ const inflected = englishInflections && wordLike
|
|
|
+ ? /[^aeiou]y$/i.test(term)
|
|
|
+ ? `${escape(term.slice(0, -1))}(?:y|ies)`
|
|
|
+ : `${escape(term)}(?:s|es)?`
|
|
|
+ : escape(term)
|
|
|
+ const expression = new RegExp(wordLike ? `(?<![A-Za-z0-9_])${inflected}(?![A-Za-z0-9_])` : inflected, 'gi')
|
|
|
+ return [...text.matchAll(expression)].map(match => match.index)
|
|
|
+}
|
|
|
+
|
|
|
+/** The two update directions a pair supports. */
|
|
|
+export type BriefDirection = 'en-to-zh' | 'zh-to-en'
|
|
|
+
|
|
|
+/** Whether a row's source-language term occurs in the given text. */
|
|
|
+function rowOccurs(row: TerminologyRow, direction: BriefDirection, text: string): boolean {
|
|
|
+ const terms = direction === 'en-to-zh' ? [row.english] : [row.first, row.chinese].filter(term => /[一-鿿]/.test(term))
|
|
|
+ return terms.some(term => termOffsets(text, term, direction === 'en-to-zh').length > 0)
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Select the terminology rows whose source-language term occurs in the
|
|
|
+ * changed text (old and new states combined).
|
|
|
+ *
|
|
|
+ * @param terminology - Full `docs/i18n/terminology.md` contents.
|
|
|
+ * @param direction - Update direction; decides which columns to match.
|
|
|
+ * @param changedText - Concatenated old and new text of the changed spans.
|
|
|
+ * @returns Matched rows in table order.
|
|
|
+ */
|
|
|
+export function relevantTerminologyRows(terminology: string, direction: BriefDirection, changedText: string): TerminologyRow[] {
|
|
|
+ return parseTerminologyRows(terminology).filter(row => rowOccurs(row, direction, changedText))
|
|
|
+}
|
|
|
+
|
|
|
+function lineAtOffset(text: string, offset: number): number {
|
|
|
+ return text.slice(0, offset).split('\n').length
|
|
|
+}
|
|
|
+
|
|
|
+function spanIndexAtOffset(text: string, spans: MarkdownSpan[], offset: number | undefined): number | undefined {
|
|
|
+ if (offset === undefined) return undefined
|
|
|
+ const line = lineAtOffset(text, offset)
|
|
|
+ return spans.find(span => line >= span.startLine && line <= span.endLine)?.index
|
|
|
+}
|
|
|
+
|
|
|
+/** First-occurrence guidance computed for a Chinese-target update. */
|
|
|
+export interface FirstOccurrenceContext {
|
|
|
+ /** Human-readable notes for the briefing. */
|
|
|
+ notes: string[]
|
|
|
+ /** Unchanged span indices that must join the briefing because a first occurrence moved into or out of them. */
|
|
|
+ extraSpanIndices: number[]
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Track document-wide first occurrences of the relevant English terms. The
|
|
|
+ * 首次出现 rendering attaches to a term's first occurrence, so when an edit
|
|
|
+ * moves that occurrence across spans, both the old and new spans need
|
|
|
+ * counterpart edits even when only one of them changed.
|
|
|
+ *
|
|
|
+ * @param confirmedSource - Last-confirmed English text.
|
|
|
+ * @param currentSource - Current English text.
|
|
|
+ * @param confirmedSpans - Spans of the last-confirmed English text.
|
|
|
+ * @param currentSpans - Spans of the current English text, aligned with `confirmedSpans`.
|
|
|
+ * @param rows - The relevant terminology rows.
|
|
|
+ * @param changed - Span indices already in the briefing.
|
|
|
+ * @returns Notes and extra span indices to include.
|
|
|
+ */
|
|
|
+export function firstOccurrenceContext(
|
|
|
+ confirmedSource: string,
|
|
|
+ currentSource: string,
|
|
|
+ confirmedSpans: MarkdownSpan[],
|
|
|
+ currentSpans: MarkdownSpan[],
|
|
|
+ rows: TerminologyRow[],
|
|
|
+ changed: Set<number>,
|
|
|
+): FirstOccurrenceContext {
|
|
|
+ const notes: string[] = []
|
|
|
+ const extra = new Set<number>()
|
|
|
+ for (const row of rows) {
|
|
|
+ if (row.first === '') continue
|
|
|
+ const oldIndex = spanIndexAtOffset(confirmedSource, confirmedSpans, termOffsets(confirmedSource, row.english, true)[0])
|
|
|
+ const newIndex = spanIndexAtOffset(currentSource, currentSpans, termOffsets(currentSource, row.english, true)[0])
|
|
|
+ if (oldIndex === newIndex) continue
|
|
|
+ for (const index of [oldIndex, newIndex]) {
|
|
|
+ if (index !== undefined && !changed.has(index)) extra.add(index)
|
|
|
+ }
|
|
|
+ notes.push(`${row.english}: the document-wide first occurrence moved from ${oldIndex === undefined ? 'absent' : `#${oldIndex}`} to ${newIndex === undefined ? 'absent' : `#${newIndex}`}; the ${row.first} form moves with it (later occurrences drop the annotation).`)
|
|
|
+ }
|
|
|
+ return { notes, extraSpanIndices: [...extra].sort((left, right) => left - right) }
|
|
|
+}
|
|
|
+
|
|
|
+/** Smallest fence of `mark` characters that safely wraps `body`. */
|
|
|
+function fenceFor(body: string, mark: '`' | '~'): string {
|
|
|
+ let longest = 2
|
|
|
+ for (const line of body.split('\n')) {
|
|
|
+ const run = new RegExp(`^\\s*(${mark === '`' ? '`' : '~'}{3,})`).exec(line)
|
|
|
+ if (run?.[1] !== undefined && run[1].length > longest) longest = run[1].length
|
|
|
+ }
|
|
|
+ return mark.repeat(longest + 1)
|
|
|
+}
|
|
|
+
|
|
|
+/** One changed (or first-occurrence) span with its three-way context. */
|
|
|
+export interface BriefBundle {
|
|
|
+ /** Span index shared by the aligned documents. */
|
|
|
+ index: number
|
|
|
+ /** Human label: heading text or node type. */
|
|
|
+ label: string
|
|
|
+ /** Why the bundle is present when its source text did not change. */
|
|
|
+ reason?: 'first-occurrence' | undefined
|
|
|
+ confirmedSourceText: string
|
|
|
+ currentSourceText: string
|
|
|
+ counterpartText: string
|
|
|
+ /** 1-based line the counterpart span starts on. */
|
|
|
+ counterpartStartLine: number
|
|
|
+}
|
|
|
+
|
|
|
+/** The granularities a briefing can map the change at, narrowest first. */
|
|
|
+export type BriefScope =
|
|
|
+ | { kind: 'mechanical' }
|
|
|
+ | { kind: 'units'; bundles: BriefBundle[]; firstOccurrenceNotes: string[] }
|
|
|
+ | { kind: 'sections'; bundles: BriefBundle[]; firstOccurrenceNotes: string[] }
|
|
|
+ | { kind: 'document'; reason: string }
|
|
|
+
|
|
|
+/** Inputs for rendering one pair's briefing. */
|
|
|
+export interface TranslationBriefInput {
|
|
|
+ /** Repo-relative path of the side that changed. */
|
|
|
+ sourcePath: string
|
|
|
+ /** Repo-relative path of the counterpart to update. */
|
|
|
+ counterpartPath: string
|
|
|
+ direction: BriefDirection
|
|
|
+ /** Unified diff of the changed side, last-confirmed to current. */
|
|
|
+ diff: string
|
|
|
+ scope: BriefScope
|
|
|
+ terminology: TerminologyRow[]
|
|
|
+}
|
|
|
+
|
|
|
+const ZH_TARGET_DIGEST = [
|
|
|
+ '- Edit ONLY what the change requires; preserve the reviewed phrasing of everything unchanged.',
|
|
|
+ '- Nothing added, nothing dropped: the Chinese must state exactly what the new English states.',
|
|
|
+ '- Write natural institutional technical Chinese, not word-by-word gloss; terse stays terse.',
|
|
|
+ '- Code fences byte-identical to the English side, comments included; inline code spans verbatim.',
|
|
|
+ '- Relative links keep the `.md` target; only the switcher line links `.zh.md`.',
|
|
|
+ '- Structure mirrors the counterpart: heading depths and order, list kinds and item counts, table rows and columns.',
|
|
|
+ '- 首次出现 annotations attach to the document-wide first occurrence only; later occurrences use the bare form, and an empty 首次出现 cell means never gloss.',
|
|
|
+ '- Typography: one half-width space between Chinese and Latin or digits; full-width punctuation in Chinese prose; 顿号 for enumerations; second person is 你.',
|
|
|
+ '- One physical line per paragraph; exactly one trailing newline.',
|
|
|
+]
|
|
|
+
|
|
|
+const EN_TARGET_DIGEST = [
|
|
|
+ '- Edit ONLY what the change requires; preserve the reviewed phrasing of everything unchanged.',
|
|
|
+ '- Nothing added, nothing dropped: the English must state exactly what the new Chinese states.',
|
|
|
+ '- Write concise professional developer prose, not word-by-word gloss; terse stays terse.',
|
|
|
+ '- Code fences byte-identical to the Chinese side, comments included; inline code spans verbatim.',
|
|
|
+ '- Relative links keep the `.md` target; only the switcher line links `.zh.md`.',
|
|
|
+ '- Structure mirrors the counterpart: heading depths and order, list kinds and item counts, table rows and columns.',
|
|
|
+ '- One physical line per paragraph; exactly one trailing newline.',
|
|
|
+]
|
|
|
+
|
|
|
+function renderBundles(out: string[], input: TranslationBriefInput, bundles: BriefBundle[], firstOccurrenceNotes: string[]): void {
|
|
|
+ const sourceLanguage = input.direction === 'en-to-zh' ? 'English' : 'Chinese'
|
|
|
+ const counterpartLanguage = input.direction === 'en-to-zh' ? 'Chinese' : 'English'
|
|
|
+ for (const bundle of bundles) {
|
|
|
+ out.push('')
|
|
|
+ out.push(`### #${bundle.index} ${bundle.label}${bundle.reason === 'first-occurrence' ? ' — unchanged; included for a first-occurrence move' : ''} — counterpart at ${input.counterpartPath}:${bundle.counterpartStartLine}`)
|
|
|
+ const fence = fenceFor([bundle.confirmedSourceText, bundle.currentSourceText, bundle.counterpartText].join('\n'), '~')
|
|
|
+ if (bundle.confirmedSourceText !== bundle.currentSourceText) {
|
|
|
+ out.push('')
|
|
|
+ out.push(`Last-confirmed ${sourceLanguage}:`)
|
|
|
+ out.push('')
|
|
|
+ out.push(`${fence}markdown`)
|
|
|
+ out.push(bundle.confirmedSourceText.trimEnd())
|
|
|
+ out.push(fence)
|
|
|
+ }
|
|
|
+ out.push('')
|
|
|
+ out.push(`Current ${sourceLanguage}:`)
|
|
|
+ out.push('')
|
|
|
+ out.push(`${fence}markdown`)
|
|
|
+ out.push(bundle.currentSourceText.trimEnd())
|
|
|
+ out.push(fence)
|
|
|
+ out.push('')
|
|
|
+ out.push(`Current ${counterpartLanguage} (bring this along):`)
|
|
|
+ out.push('')
|
|
|
+ out.push(`${fence}markdown`)
|
|
|
+ out.push(bundle.counterpartText.trimEnd())
|
|
|
+ out.push(fence)
|
|
|
+ }
|
|
|
+ if (firstOccurrenceNotes.length > 0) {
|
|
|
+ out.push('')
|
|
|
+ out.push('## First-occurrence notes')
|
|
|
+ out.push('')
|
|
|
+ for (const note of firstOccurrenceNotes) out.push(`- ${note}`)
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Render the complete briefing for one out-of-sync pair.
|
|
|
+ *
|
|
|
+ * @param input - Diff, mapped scope, terminology, and pair identity.
|
|
|
+ * @returns Markdown briefing text.
|
|
|
+ */
|
|
|
+export function renderTranslationBrief(input: TranslationBriefInput): string {
|
|
|
+ const sourceLanguage = input.direction === 'en-to-zh' ? 'English' : 'Chinese'
|
|
|
+ const counterpartLanguage = input.direction === 'en-to-zh' ? 'Chinese' : 'English'
|
|
|
+ const out: string[] = []
|
|
|
+ out.push(`# Translation update briefing: ${input.sourcePath}`)
|
|
|
+ out.push('')
|
|
|
+ out.push(`The ${sourceLanguage} side changed; bring \`${input.counterpartPath}\` along with the smallest edit that covers the change.`)
|
|
|
+ if (input.scope.kind === 'mechanical') {
|
|
|
+ out.push('')
|
|
|
+ out.push('## Mechanical update — no translation judgment involved')
|
|
|
+ out.push('')
|
|
|
+ out.push(`Every change since the last confirmed state is inside fenced code blocks, which are byte-identical across the pair. Run \`pnpm run gen-translation-brief --apply ${input.sourcePath}\` to splice the updated fences into the counterpart (the result is structure-validated before writing), then record per the Finish steps.`)
|
|
|
+ }
|
|
|
+ out.push('')
|
|
|
+ out.push(`## ${sourceLanguage} diff (last-confirmed → current)`)
|
|
|
+ out.push('')
|
|
|
+ const diffFence = fenceFor(input.diff, '`')
|
|
|
+ out.push(`${diffFence}diff`)
|
|
|
+ out.push(input.diff.trimEnd())
|
|
|
+ out.push(diffFence)
|
|
|
+ switch (input.scope.kind) {
|
|
|
+ case 'mechanical':
|
|
|
+ break
|
|
|
+ case 'units':
|
|
|
+ out.push('')
|
|
|
+ out.push(`## Changed units (last-confirmed ${sourceLanguage} → current ${sourceLanguage}, with the current ${counterpartLanguage})`)
|
|
|
+ renderBundles(out, input, input.scope.bundles, input.scope.firstOccurrenceNotes)
|
|
|
+ break
|
|
|
+ case 'sections':
|
|
|
+ out.push('')
|
|
|
+ out.push('## Changed sections (fine-grained units do not align across the pair; whole heading sections shown)')
|
|
|
+ renderBundles(out, input, input.scope.bundles, input.scope.firstOccurrenceNotes)
|
|
|
+ break
|
|
|
+ case 'document':
|
|
|
+ out.push('')
|
|
|
+ out.push('## Whole-document update required')
|
|
|
+ out.push('')
|
|
|
+ out.push(`${input.scope.reason} Open \`${input.counterpartPath}\` directly, locate the affected regions yourself, and reconcile under docs/i18n/translation-rules.md.`)
|
|
|
+ break
|
|
|
+ default:
|
|
|
+ input.scope satisfies never
|
|
|
+ }
|
|
|
+ if (input.terminology.length > 0) {
|
|
|
+ out.push('')
|
|
|
+ out.push('## Binding terminology rows matching this change (docs/i18n/terminology.md)')
|
|
|
+ out.push('')
|
|
|
+ out.push('| English | 中文 | 首次出现 | 不要译作 | 备注 |')
|
|
|
+ out.push('|---|---|---|---|---|')
|
|
|
+ for (const row of input.terminology) out.push(row.line)
|
|
|
+ out.push('')
|
|
|
+ out.push('For any term you introduce that is not listed above, consult the full table before inventing a rendering.')
|
|
|
+ }
|
|
|
+ out.push('')
|
|
|
+ out.push('## Rules digest (full rules: docs/i18n/translation-rules.md)')
|
|
|
+ out.push('')
|
|
|
+ out.push(...(input.direction === 'en-to-zh' ? ZH_TARGET_DIGEST : EN_TARGET_DIGEST))
|
|
|
+ out.push('')
|
|
|
+ out.push('## Finish')
|
|
|
+ out.push('')
|
|
|
+ out.push('1. Apply the smallest counterpart edit that covers the change, then verify the changed spans clause by clause against the source.')
|
|
|
+ out.push(`2. \`pnpm run verify-translation-pairing --write ${input.sourcePath.replace(/\.zh\.md$/, '.md')}\``)
|
|
|
+ out.push(`3. \`pnpm run verify-translation-pairing ${input.sourcePath.replace(/\.zh\.md$/, '.md')}\``)
|
|
|
+ out.push('')
|
|
|
+ return out.join('\n')
|
|
|
+}
|
imccyu