Agent化文档翻译：从“能翻译”到“可执行交付”

很多翻译项目的问题，不是"翻得不像人"，而是交付物不稳定。

让模型翻一段不难；真正难的是把任务推进到"把真实网页或 Markdown 稳定交付成结构不坏的中文 Markdown 文件"。一旦目标变成后者，问题就不只是语言转换，而是完整的工程执行。

Translator 仓库最值得写的，不是"它用了 Flask + DeepSeek"，而是背后的 agent 构建范式：plan-and-execute、整体到部分、ReAct 循环，以及质量兜底。它不是把 LLM 当"会翻译的函数"，而是包进一条能落地、能验收、能反复执行的交付流水线。

一、不是翻译 demo，是本地优先的文档交付链路

Translator 是一个把网页或本地 Markdown 转成中文 Markdown 的本地优先工具，提供 CLI 和 Web 双入口。表面像翻译器，实际是受约束的 agent 工作流：

1. 读取清洗输入
2. 为整个文档建立全局 profile
3. 拆成 chunk 并发翻译
4. 结构恢复、自动修复和 lint 校验
5. 残留英文定点修补
6. 写出真正的 Markdown 文件

不是"调一次模型接口返回字符串"，而是有计划、有执行、有检查、有补救的完整过程。

二、架构：共享后端，统一流水线

CLI 和 Web 不各写一套逻辑，共用同一条后端翻译流水线：

核心模块：

• core/pipeline.py：翻译主流程编排
• core/step1_profile.py：文档级全局 profile（术语表、标题风格、语言偏好）
• core/step2_translate.py：chunk 翻译 + 占位符保护 + 重试修补
• markdown/*：sanitize / normalize / autofix / lint 四道护栏
• llm/client.py：OpenAI-compatible 客户端 + 自动重试

三、Profile 生成：先理解全局再动手

翻译前先为整篇文档建一个 profile：术语倾向、人名地名处理方式、代码语言、标题层级风格。这个 profile 会注入每个 chunk 的翻译 prompt。

没有全局 profile，chunk 之间术语漂移、层级错乱是必然的。这一步把"一篇文档"的信息压缩成一个轻量上下文约束，避免逐 chunk 丢失全局视野。

四、占位符保护：翻译不能破坏结构

Markdown 的结构非常脆。代码块、行内代码、LaTeX 公式、链接、图片引用——模型一碰就坏。Translator 的做法是翻译前先用占位符替换所有敏感结构，翻译完再恢复。

不是新思路，但实现上几个细节值得注意：

• 占位符用了足够显眼的 pattern，降低模型误改概率
• 恢复阶段做了 post-check，确保占位符数量进出一致
• 如果恢复失败，触发定点修补而不是整段重翻

五、ReAct 式修补：失败不是终点

这是整个项目最有 agent 味的部分。翻译完 lint 后，如果发现残留英文、结构破损、占位符未恢复，系统不会报错退出，而是进入 ReAct 循环：

1. 检测问题（observe）
2. 定位问题位置（think）
3. 生成修复 action（act）
4. 重新校验（observe）

最多循环 3 轮。大部分情况下 1-2 轮就能修好。

普通翻译脚本失败就失败了。Agent 化系统的区别在于：它能在失败后自己补救。

六、质量兜底：Markdown lint + autofix

翻译后跑一道自定义 lint：标题层级是否连续、列表缩进是否一致、代码块是否闭合、链接是否完整、残留英文比例是否过高。能自动修的自动修，修不了的标记出来交给 ReAct 循环。

这道兜底让系统的下限不会太低，即使模型偶尔抽风，最终交付物至少结构是完整的。

七、Plan-and-Execute：拆与合的节奏

整个翻译流程本质上是 plan-and-execute 模式：

• Plan：profile 生成 + 分块策略
• Execute：按 chunk 并发翻译
• Verify：lint + 占位符恢复检查
• React：定点修补循环

这比"整篇扔给模型"更可控，也比"逐段翻译无全局视野"更稳。拆是为了并发和控制粒度，合是为了术语一致和上下文连贯。

八、如果我来做改进

• 增量翻译：文档改了某段，只重翻那段而非整篇
• 术语表持久化：profile 跨文档复用，同一作者的文章术语统一
• 并行度自适应：根据文档长度和模型并发能力动态调 chunk 大小
• 交付物格式扩展：不只是 .md，还能输出 .docx 或 .epub

九、总结

Translator 真正值得看的，不是"接了一个翻译模型"，而是它把文档翻译做成了一条具备计划、分解、反馈修补与质量兜底能力的 agent 化交付流水线。

不是追求一次回答多聪明，而是让系统在真实任务里，稳稳地把事情做完。