feat(ai): coordinate long-document translation

Author: Innei

apps/core/src/modules/ai/ai-translation/engine/translation-agent.ts

@@ -13,7 +13,9 @@ import {
 import type { PipelineMetrics } from '../translation-strategy.interface'
 import type { TranslationUnit } from '../translation-unit.types'
 import { flatIdsOf, unitsToSourceMap } from '../translation-unit.types'
+import { shouldUseChunkedTranslation } from './translation-chunk-planner'
 import { createTranslationConversation } from './translation-context'
+import { runChunkedTranslationAgent } from './translation-coordinator'
 import { createTranslationTools, TRANSLATION_FILE } from './translation-tools'
 
 export const AGENT_MAX_STEPS = 12
@@ -51,6 +53,25 @@ export async function runTranslationAgent(opts: {
     throw new TypeError('runtime does not implement streamMessage')
   }
 
+  if (shouldUseChunkedTranslation(units)) {
+    logger.log(
+      `Long document detected: units=${units.length}; using translation coordinator`,
+    )
+    return runChunkedTranslationAgent({
+      targetLang,
+      units,
+      documentContext,
+      styleHints,
+      runtime,
+      reviewerRuntime,
+      signal,
+      onToken,
+      onCost,
+      onSegments,
+      metrics,
+    })
+  }
+
   const vfs = new VirtualFs()
   let reviewer: SubAgentSpec | undefined
   if (reviewerRuntime) {

apps/core/src/modules/ai/ai-translation/engine/translation-chunk-planner.ts

@@ -0,0 +1,84 @@
+import type { TranslationUnit } from '../translation-unit.types'
+import { flatIdsOf } from '../translation-unit.types'
+
+export const DIRECT_TRANSLATION_MAX_SOURCE_CHARS = 12_000
+export const DIRECT_TRANSLATION_MAX_SEGMENTS = 240
+export const TRANSLATION_CHUNK_MAX_SOURCE_CHARS = 6_000
+export const TRANSLATION_CHUNK_MAX_SEGMENTS = 120
+
+export interface TranslationChunk {
+  id: string
+  units: TranslationUnit[]
+  sourceChars: number
+  segmentCount: number
+}
+
+export interface TranslationLoad {
+  sourceChars: number
+  segmentCount: number
+}
+
+export const translationUnitSourceChars = (unit: TranslationUnit): number => {
+  if (typeof unit.payload === 'string') return unit.payload.length
+  return unit.payload.segments.reduce(
+    (total, segment) => total + segment.text.length,
+    0,
+  )
+}
+
+export const estimateTranslationLoad = (
+  units: readonly TranslationUnit[],
+): TranslationLoad => ({
+  sourceChars: units.reduce(
+    (total, unit) => total + translationUnitSourceChars(unit),
+    0,
+  ),
+  segmentCount: flatIdsOf([...units]).length,
+})
+
+export const shouldUseChunkedTranslation = (
+  units: readonly TranslationUnit[],
+): boolean => {
+  const load = estimateTranslationLoad(units)
+  return (
+    load.sourceChars > DIRECT_TRANSLATION_MAX_SOURCE_CHARS ||
+    load.segmentCount > DIRECT_TRANSLATION_MAX_SEGMENTS
+  )
+}
+
+export const planTranslationChunks = (
+  units: readonly TranslationUnit[],
+): TranslationChunk[] => {
+  const chunks: TranslationChunk[] = []
+  let pending: TranslationUnit[] = []
+  let sourceChars = 0
+  let segmentCount = 0
+
+  const flush = () => {
+    if (pending.length === 0) return
+    chunks.push({
+      id: `chunk-${chunks.length + 1}`,
+      units: pending,
+      sourceChars,
+      segmentCount,
+    })
+    pending = []
+    sourceChars = 0
+    segmentCount = 0
+  }
+
+  for (const unit of units) {
+    const unitSourceChars = translationUnitSourceChars(unit)
+    const unitSegmentCount = unit.memberIds?.length ?? 1
+    const exceedsBudget =
+      pending.length > 0 &&
+      (sourceChars + unitSourceChars > TRANSLATION_CHUNK_MAX_SOURCE_CHARS ||
+        segmentCount + unitSegmentCount > TRANSLATION_CHUNK_MAX_SEGMENTS)
+    if (exceedsBudget) flush()
+    pending.push(unit)
+    sourceChars += unitSourceChars
+    segmentCount += unitSegmentCount
+  }
+  flush()
+  return chunks
+}

apps/core/src/modules/ai/ai-translation/engine/translation-context.ts

@@ -2,6 +2,7 @@ import { AI_PROMPTS } from '../../ai.prompts'
 import { Conversation } from '../../message-engine/conversation/conversation'
 import type { TranslationUnit } from '../translation-unit.types'
 import { unitsToEntries, unitsToMeta } from '../translation-unit.types'
+import type { TranslationChunk } from './translation-chunk-planner'
 
 export function createTranslationConversation(opts: {
   targetLang: string
@@ -24,3 +25,31 @@ export function createTranslationConversation(opts: {
   conversation.appendUser(prompt)
   return conversation
 }
+
+export function createTranslationCoordinatorConversation(opts: {
+  targetLang: string
+  chunks: readonly TranslationChunk[]
+  reviewEnabled: boolean
+}): Conversation {
+  const { targetLang, chunks, reviewEnabled } = opts
+  const reviewWorkflow = reviewEnabled
+    ? 'After every chunk is complete, call request_review. If it reports issues, read only the cited ids with read_translation_segments, patch them, and request review again. Finish after a clean review or when the review budget is exhausted.'
+    : 'After every chunk is complete, finish with a short confirmation.'
+  const conversation =
+    new Conversation(`You coordinate a long-document translation into ${targetLang}.
+
+Do not translate prose yourself. The source text is intentionally hidden from this conversation. Delegate work through translate_chunks, which runs isolated translation sub-agents with bounded concurrency.
+
+Call translate_chunks with all pending chunk ids. If any chunk fails, retry only the failed ids. Use translation_status when coverage is uncertain. Never invent chunk ids.
+
+${reviewWorkflow}`)
+  conversation.appendUser(`Translate every chunk in this manifest:
+${JSON.stringify(
+  chunks.map((chunk) => ({
+    id: chunk.id,
+    sourceChars: chunk.sourceChars,
+    segmentCount: chunk.segmentCount,
+  })),
+)}`)
+  return conversation
+}