baoyu-translate实战：用术语表和审校流程翻译技术文章

返回总教程

baoyu-translate 的核心不是把英文逐句换成中文，而是把译文生产拆成可检查的步骤：先理解内容与术语，再翻译，必要时独立批评、修订和润色。尤其需要注意，它的命令行脚本主要负责 Markdown 分块，真正的翻译由 Agent 完成。

本文基于固定提交源码核对。案例为操作示例，不是付费翻译、在线模型或账号实测；撰写时未运行技能、安装依赖或生成实际译稿。

一、适用场景与能力边界

适合英文技术博客、产品说明、研究解读和需要统一术语的长文。输入可以是本地文件、粘贴文本或 URL。URL 输入仍需要先取得合法可访问的正文；翻译技能不能把登录墙后不存在于上下文中的内容“翻译出来”。

三种模式对应不同成本与质量目标：

模式	工作流程	适合场景
quick	直接翻译	短通知、理解一句话、非正式内容
normal	分析、组装提示、翻译	一般技术文章与博客
refined	分析、初稿、批评、修订、润色	需要公开发布或认真引用的稿件

“精翻”不等于事实验证，也不是专业领域认证。数字、因果、否定、条件和引用仍要对照原文。法律、医疗或合同类重要文件，应让相应专业人员复核，不能把语言自然当成内容可靠。

另一个边界是图片。技能可以提醒哪些图里仍有源语言文字，但不会默认重画、OCR 或翻译图片文字。文章中文化后，图中英文标签仍可能存在，需要单独决定是否处理。

二、前置依赖与按需安装

需要具备读写文件能力的 Agent；长文分块依赖 Bun 或通过 npx -y bun 调用的 Bun。短文翻译主要是 Agent 工作流，不应误称必须先配置一个单独的翻译 API Key。

仓库 README 提供安装入口，本系列另核实 skills CLI 1.7.2 的按需选择参数：

1	npx skills add jimliu/baoyu-skills --skill baoyu-translate --agent codex

按需选择 baoyu-translate。若用 Codex 项目级安装，应保留完整技能目录，包含术语参考、审校流程、分块脚本与 package.json。该安装命令不锁定提交，最新安装不等于固定快照；严格复现本文需使用固定提交对应目录。

已核实的分块命令如下，{baseDir} 与文件路径均需替换：

1	npx -y bun "{baseDir}/scripts/main.ts" "article.md" --max-words 5000 --output-dir "article-work"

这条命令只分块，不会自动调用模型完成翻译。虽然 SKILL 的工作流表出现 --to、--mode、--audience 等表达，当前 scripts/main.ts 实际入口只有分块及其选项。不要编造 main.ts article.md --mode refined --to zh-CN 这种“全自动翻译命令”；语言、模式和受众用自然语言交给 Agent。

三、输入输出与中间文件

本地文件直接作为来源，不需要复制；粘贴文本或 URL 内容先落为 translate/{slug}.md。译文目录位于来源旁边，形态为 {原文件名}-{目标语言}/。目标语言代码应由 Agent 明确报告，不要把示例里的 zh 当作所有情况都使用的目录后缀。

所有模式最终都写 translation.md。普通模式还包含 01-analysis.md 与 02-prompt.md；精翻增加 03-draft.md、04-critique.md、05-revision.md。长文另有 chunks/ 保存原文分块和翻译分块。输出目录已经存在时，参考流程要求先重命名备份，再建立新目录，不能静默覆盖。

这些文件帮助定位错误：术语理解错误查分析，反复用错译名查共享提示，漏译查分块，润色偏离原意则对照初稿和批评。若只收到一个漂亮的最终文件，却没有请求模式要求的中间稿，工作流可能没有完整执行。

四、配置与术语管理

配置按项目、XDG、用户目录顺序查找，第一个命中生效：

1
2
3

.baoyu-skills/baoyu-translate/EXTEND.md
${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md
$HOME/.baoyu-skills/baoyu-translate/EXTEND.md

没有配置时必须先询问目标语言、模式、受众、风格和保存范围。下面是面向开发者的配置示例，不表示本次已经写入：

target_language: zh-CN
default_mode: normal
audience: technical
style: technical
chunk_threshold: 4000
chunk_max_words: 5000
glossary:
  - from: "AI Agent"
    to: "AI 智能体"
  - from: "Transformer"
    to: "Transformer"
    note: "保留英文模型架构名称"

audience 决定解释深度，style 决定表达方式，二者不应混同。普通读者可能需要少量术语解释，技术读者通常不需要反复解释 API。默认叙事风格不一定适合工程说明，应主动指定 technical 或其他合适风格。

术语可直接写在 glossary，也可用 glossary_files 指向 Markdown 表格或 YAML 列表，相对路径以 EXTEND.md 所在目录为基准。语言对专用 glossaries 的优先级高于通用内联词表，内联高于外部文件，内置词表兜底。任务临时指定的术语应由 Agent 纳入本次共享上下文，不要依赖不存在的翻译 CLI 自动读取参数。

五、可复制的自然语言 Agent 请求

请使用 baoyu-translate 翻译 [源文件绝对路径]，目标为简体中文。
采用 refined 模式，读者是开发者，风格 technical。
先读取 EXTEND.md；缺失时先确认配置，不静默写默认值。
把 AI Agent 统一译为“AI 智能体”，Transformer 保留英文。
数字、否定、条件、链接和代码必须忠实保留，不省略原文段落。
长文先抽取全篇术语，再分块；保留分析、提示、初稿、批评、修订和最终稿。
存在旧输出时先备份。完成后列出图片语言可能不一致的地方，只提醒，不改图，不发布。

已有普通模式译文时可以接着说：

1
2
3

请基于刚才的 translation.md 继续审校和润色，不重新抓取来源。
先保留当前稿为初稿，批评文件只写问题诊断，再逐项修订。
重点检查术语一致性、比较关系、条件句和代码说明，不把译者推断写成作者原话。

六、操作案例：翻译一篇长技术文章

假设本地有一篇约六千英文词的代理系统文章，包含代码、两张图片和重复出现的术语。目标是给团队做中文阅读材料。以下是工作流示例，不是已完成翻译的报告。

检查原文。 确认开头、中间、结尾齐全，代码围栏闭合，图片链接存在。来自网页时先验收采集结果，不能在残缺正文上讨论翻译质量。
先定全篇词表。 提取 Agent、tool call、context 等词，按语境确定译法。共享词表应在分块前生成，避免不同子任务各自决定术语。
按 Markdown 结构分块。 normal/refined 默认在四千词阈值触发分块，每块上限默认五千词；优先按块边界切分。极大单块仍可能退回行或词级切分，因此不能承诺任何代码块绝不会被拆。
翻译并有序合并。 有子 Agent 时每块使用相同共享提示与位置说明，无子 Agent 时顺序处理也可。合并按原始顺序，检查段落和标题没有重复、丢失。
独立批评与修订。 04-critique.md 只诊断，不伪装成另一份终稿。重点查数字、因果方向、语气强弱、术语漂移与中文不自然句式，再产出修订稿和最终稿。
检查双端使用。 Obsidian 中打开最终稿，检查图片相对路径。译文位于新子目录，原图未必跟着移动，不能保证自动可用。准备 Hexo 时保留来源、核对元数据并只发布最终稿，不把分析文件全送进博客。

七、长文与元数据的注意点

quick 模式不分块，即使原文很长也如此；超过阈值应提示用户换 normal，而不是暗中改变模式。分块能减少上下文压力，但不自动保证术语百分之百一致，最终仍需全篇搜索核心词。

原文 YAML 中的来源元数据会按规则改为 source 前缀，例如 url 到 sourceUrl，并添加译后字段；其他字段保留。若正文已有一级标题，规则可能不再新增顶层 title，所以 Hexo 发布前要检查站点实际需要的标题字段。不要让翻译流程覆盖自己既定的 slug 或把来源文章的发布日期误当成当前译稿发布日期。

译者解释应少量、明确，与作者原意区分。润色允许改善中文语序，但不能扩展论点、补充不存在的性能结论或替作者提高确定性。