longtext-translate

文本翻译

本技能提供三条翻译路径，根据文本规模和用户需求自动判断或由用户指定：

1. 普通翻译：主 agent 在单一上下文中完成翻译。适合短文本和论证紧密、不宜分片的文章。
2. 长文本翻译：先分片，再建立共享上下文并委派 subagent 并行翻译各分片，最后合并。适合可稳定拆分的长文。
3. 译稿审校/精编：对已有译文进行审校或精编处理。既可承接前两种路径，也可在用户直接提供原文与译稿时独立执行。

前置准备

第 1 步：规范化源内容

翻译流程只接受 Markdown 输入。用户提供的原始内容都需先规范化为本地 Markdown 文件。后续的翻译、审校、分片和合并均以该 Markdown 文件作为唯一输入源（源文件）。

输入类型	动作
文本或 Markdown 文件	直接使用
内联文本	保存为 translate/{slug}.md
PDF/图片/Word 文档	按 references/ingest/mineru.md 处理
EPUB 文件	按 references/ingest/epub.md 处理
URL	使用当前环境允许的网页访问能力抓取正文并整理；若无自然文件名，保存为 translate/{slug}.md
只翻译部分内容	抽取指定章节、页码或标题范围

{slug} 根据内容主题生成 2–4 个词并采用 kebab-case。

PDF、图片、Word、EPUB 文档或 URL 输入经规范化后，向用户汇报提取结果和文件路径，并附上建议：“若内容无误，建议执行 /clear 或其他等效命令清空上下文，再从该 Markdown 文件重新进入翻译流程——干净的上下文能达到更好的翻译效果。” 汇报完成后即停止，等待用户确认，不进入第 2 步。

Markdown 或纯文本输入规范化后可直接进入第 2 步。

第 2 步：制定并确认翻译方案

① 整理翻译偏好

• 目标语言：默认简体中文，用户可自行指定。
• 目标读者：默认为希望准确、无障碍理解原文内容的读者，用户可自行指定。
• 用户术语约束：用户显式提供的术语要求，例如术语表文件、命令中直接写出的术语映射、保留原文或指定译法等。非必须项；若有则完整收集并全程应用。若该约束是条目庞大的术语表文件（数百条以上），不要全量读入上下文，改按 references/terminology.md 的方式按需筛选出源文实际出现的子集再应用。

② 决定翻译策略

1. 选择任务类型
   • 用户提供原文与译稿并要求审校/精编：直接进入对应流程。
   • 其他情况：进入翻译流程。
2. 选择翻译方式
   • 用户已指定普通翻译或长文本翻译：直接采用。
   • 未指定：读取 references/metadata.json。若能识别当前模型且匹配到对应条目，使用该条目的 chunkThreshold 阈值；否则使用 fallback。估算待译文本词数。低于阈值采用普通翻译，高于阈值采用长文本翻译。

③ 准备输出目录

明确策略后，在源文件同级目录下创建输出目录，路径格式为 {source-dir}/{source-basename}-{target-lang}/。

示例：

• posts/article.md → posts/article-zh/
• translate/ai-future.md → translate/ai-future-zh/

复用现有输出目录时，至少确认以下条件一致：源文件相同、目标语言相同、当前任务属于同一轮翻译、同一轮审校或同一轮精编。满足这些条件时，直接沿用原有目录及其中间文件；否则路径改为 {source-dir}/{source-basename}-{target-lang}-MMDD-HHmm/，MMDD-HHmm 替换为当前日期和时间。

创建或复用输出目录后，检查源文件同级是否存在 {source-basename}_images/ 目录。若存在且输出目录内尚无同名目录，则将其复制进去（cp -r {source-dir}/{source-basename}_images/ {output-dir}/），确保译文中的相对图片路径能正常解析。若输出目录内已有该目录则跳过。

④ 生成分片预览（仅限长文本翻译模式）

如采用长文本翻译模式，先执行以下命令：

python3 {baseDir}/scripts/chunk.py preview <file> [--max-words <chunk_max_words>] --output-dir <output-dir>

其中，{baseDir} 为本 SKILL.md 所在目录，<chunk_max_words> 使用前述阈值中的 chunkThreshold。依赖 markdown-it-py>=4.0,<5。

此命令将生成 chunk-preview.html，并自动启动本地预览服务，但不会立即创建 chunks/ 文件夹。用户可通过命令返回的 preview_url 查看分片预览页面，按需调整分片边界。若用户在页面中确认方案，脚本会保存 chunk-plan.json；后续命令优先采用该方案。

⑤ 声明翻译计划并等待确认

正式执行前，向用户一次性说明：

• 当前任务入口：从原文生成译稿，或审校/精编已有译稿
• 翻译路径：普通翻译或长文本翻译，以及判断依据
• 目标语言、目标读者、用户术语约束、输出目录
• 长文本模式下的分片预览入口 preview_url

用户确认后开始正式执行。

翻译执行

第 1 步：理解内容并确定译法

基于确认后的策略、目标读者和术语约束，分析源材料并确定译法：

• 内容：核心论点、作者背景或立场、写作语境、原文目的与预期受众。
• 术语：识别需要全局统一的核心术语，与用户术语约束交叉核对，确定一致译法；对于未覆盖的专业术语，使用行业公认的标准译法。
• 语域锚定：判断原文的正式度、口语度、情感强度和体裁风格，确定译文应保持的语域。
• 翻译难点：识别隐喻、习语、双关、文字游戏、长难句等需要创造性处理的结构。

普通翻译模式下，分析只作为内部执行依据，无需生成中间文件或向用户输出。

长文本翻译模式下，将分析结果保存为两份共享文件：

1. glossary.md：提取术语维度的判断结果，列出每条术语的原文、推荐译法和简要理由。用户提供的术语约束也合并进，冲突时以用户约束为准。
2. prompt.md：按 references/prompt-template.md 的结构组装。内容、语域锚定和翻译难点三个维度的分析结果分别填入模板的对应槽位，同时写入目标语言、目标读者和翻译原则。

第 2 步：翻译正文

翻译时遵守以下原则：

• 重写，而不只是翻译：在不改变原意的前提下，按目标语言习惯重组句式、信息顺序和段落节奏，就像母语写作者从零开始创作。
• 忠实原文：完整保留原文事实、数据、观点、逻辑关系和论证结构。
• 语气与语域匹配：等价再现原文的口语化程度、情感强度、讽刺、幽默和体裁风格。
• 保留 Markdown 结构：标题、粗体、链接、图片、代码块、脚注等结构性标记须原样保留。
• 术语一致：遵守用户提供的术语约束。未覆盖的专业术语使用行业公认的标准译法。专业术语/人名/书名首次出现时，在译文后用括号标注原文。
• 报告低争议修正：原文存在拼写错误、明显 OCR 错字等低争议错误时，可在译文中直接修正，但译后必须向用户汇报。

长文本翻译模式的执行流程

普通翻译模式直接由主 agent 按上述原则翻译并保存为 translation.md。长文本翻译模式需按如下步骤执行：

1. 执行命令将分片落地：python3 {baseDir}/scripts/chunk.py materialize <file> [--max-words <chunk_max_words>] --output-dir <output-dir>
   • 脚本会优先读取 chunk-plan.json，否则采用默认分片方案。
   • 返回 JSON 中的 chunk_index 提供每个 chunk 的编号、词数和起始标题路径。
2. 委派 subagent 翻译：为每个分块启动一个 subagent，按 references/prompt-template.md 的启动提示组织任务。每个 subagent 读取 prompt.md 获取共享上下文，接收分块位置信息，翻译自己的分块并保存为 chunks/chunk-NN-draft.md。
3. 合并：所有 subagent 完成后，按顺序合并已翻译分块。若存在 chunks/frontmatter.md 则置于开头。保存为 translation.md。所有源分块与已翻译分块均保留在 chunks/ 中。

第 3 步：质量门禁

回源抽查 translation.md，检查以下维度，发现问题直接修正：

• 准确性：事实、数据、观点、逻辑关系和作者立场无偏移
• 完整性：无漏译、增译、跳段或重复
• 语气：情感强度和语域与原文匹配，口语、讽刺和幽默未被中性书面语抹平
• 术语：用户指定术语正确应用，核心术语全文一致，专业术语首次出现标注原文
• 格式：Markdown 结构完整可用，长文是否已按译法判断启用关键句加粗或小标题
• 可读性：无病句和明显翻译腔，指代清楚，句长和信息密度符合目标语言习惯

第 4 步：增强路由与完成汇报

如果用户在最初的需求中已明确提出需要审校或精编，则直接进入对应流程。审校详见 references/review.md，精编详见 references/polish.md，双语版详见 references/bilingual.md。

如用户未提前说明，则：

1. 向用户简明汇报当前进度——译文的保存路径，以及是否修正了原文中的低争议问题。
2. 询问用户是否需要继续执行以下操作，列出带数字序号的选项，用户输入数字即是选择：
   1. 审校：逐段对照原文核查译文，形成结构化诊断报告并修订问题；修正完成后通读顺平译文，确保行文流畅自然。
   2. 精编：将译文作为独立的目标语言文章做最终打磨，提升阅读体验。可按需显化重点与结构、补充背景解释、统一中文排版与格式。
   3. 审校 + 精编：先审校修正问题，再精编提升阅读体验。
   4. 双语版：将原文与译文按段落交替排列，产出便于对照阅读的双语文件。

注意：无论双语版是用户预先指定还是通过选项选中，它始终在所有质量相关步骤（翻译、可选审校、可选精编）完成后才执行——它是格式化步骤，不介入翻译质量环节。

各流程结束后同样需要汇报完成情况，内容至少包括：产出的文件路径。

附录：参考文件

文件	适用场景	何时读取
references/metadata.json	翻译策略判断	决定翻译路径前，获取当前模型的 chunkThreshold 阈值
references/terminology.md	大型术语表	用户提供条目庞大的术语表文件时，按需筛选出源文实际出现的子集
references/prompt-template.md	长文本翻译	定义 prompt.md 与 subagent 启动提示的模板
references/review.md	审校	审校流程执行细节
references/polish.md	译文精编	精编流程执行细节
references/ingest/mineru.md	PDF/图片/Word 文档输入	源材料为文档文件时，按流程规范化为 Markdown
references/ingest/epub.md	EPUB 输入	源材料为 EPUB 时，按流程规范化为 Markdown
references/bilingual.md	双语版输出	产出原文与译文交替排列的双语版本的操作指南

附录：输出文件参考

文件	出现场景	说明
translation.md	所有模式	最终译文
chunk-preview.html	长文本	分片预览页面；用户应通过 preview_url 打开
chunk-plan.json	长文本	用户在预览页面调整过分片并确认时才会生成；若未生成则按默认分片执行
glossary.md	长文本	供 subagent 共用的术语表
prompt.md	长文本	面向 subagent 的共享翻译提示
chunks/	长文本	分片目录。包含源分片 chunk-NN.md、译文分片 chunk-NN-draft.md，以及可能存在的 frontmatter.md
draft.md	审校/精编	增强流程开始前的译稿快照
critique.md	审校	结构化、可证伪的独立审校报告
polish-preview.html	精编	中文排版与格式修正的预览页面；用户应通过 preview_url 打开
mapping.json	双语版	源文与译文的块级对齐映射，由 agent 分析两份 dump 输出后生成
bilingual.md	双语版	原文与译文按段落交替排列的双语输出文件