文档翻译（doc-translate）

你要解决的事

用户给你一份文档（常是外语合同、表单、说明书、报价单），他要的是三件事：

1. 看懂 —— 关键信息提出来（谁发的、给谁的、要干什么、有什么条款）
2. 中文对照 —— 逐段翻译，能和原文对照着看
3. 留档 —— 落盘成 Markdown，能传给同事、能进知识库

本技能是科码自建技能。未来要在翻译这件事上叠加自有的口径/术语表/模板，都在这里长。

三条铁律

1. 先用脚本提取，别硬读文件 —— Direct Read 一个 PDF 会直接报错（缺 pdftoppm），而且拿不到结构化分页。脚本 20 秒搞定的事，不要在工具选择上试错。
2. 翻译就是翻译 —— 默认 1:1 完整翻译，不因"安全"擅自删减。脱敏是使用者的可选要求，不是默认行为——擅自脱敏 = 交出一份残缺的翻译，等于没完成工作。
3. 提取不到就说提取不到 —— 扫描件、无文本层、字体乱码，如实标注，不要脑补内容。翻译错了比没翻译更危险。

第 0 步：提取文本（全自动，别问用户）

bash <本技能目录的绝对路径>/scripts/extract-doc.sh "<文件绝对路径>"

先把文件复制/保存到本地磁盘——云盘占位符文件（.icloud、未下载的 OneDrive 项）会读不到内容。

脚本会自动探测工具链，缺什么装什么：

先跑一次环境自检（想知道为什么失败时）：

bash <本技能目录的绝对路径>/scripts/extract-doc.sh --check

输出示例：

python3 : ✅ /opt/homebrew/bin/python3
pdftotext: ⚪ 未装（可用，PDF 会退回 pypdf，慢一些）
pypdf    : ⚪ 未就绪（首次提取 PDF 时自动装，约 20 秒）

⚠️ 别自己乱试工具。踩过的坑：strings 对压缩 PDF 无效；Read 工具读 PDF 需要 pdftoppm；pip install 在 macOS 上被 PEP 668 拦（外部管理环境）必须用 venv。脚本里已经把这些坑都绕开了，直接用就行。

提取完先看这两样

第 1 步：读懂（先判断这是什么文档）

别急着逐字翻译，先定性。 这一步决定后面怎么翻：

📌 定性要克制：只写这份文档里实际有的内容。不要因为"A 邮件没提 B"就推断"B 有问题"——A 没提 B 通常只是因为B 不在 A 的范围内。交叉解读出来的矛盾，多半是自造的。

第 2 步：翻译（中英对照）

输出格式

短文档 / 表单类 → 用中英对照表格（最好读）：

| 原文 | 译文 |
|------|------|
| Employees should not install... | 员工不得安装…… |

长文档 / 合同条款 → 用分节对照：

**§3.2 Termination**

> **原文**
> Either party may terminate this Agreement upon thirty (30) days' written notice.

> **译文**
> 任何一方均可提前三十（30）日书面通知终止本协议。

翻译要求

• 术语一次定，全文统一 —— 同一术语前后译法必须一致；首次出现可附英文原文
• 数字、日期、金额、编号：原样保留，不换算、不推断
• 法律/责任条款：直译优先，不美化、不弱化措辞（"may result in disciplinary actions" 就是"可能面临纪律处分"，不译成"可能被提醒"）
• 拿不准的地方加标注，例如 （此处原文表述为 XXX，含义务性，建议法务复核）

会议逐字稿翻译（特殊场景，另一套规矩）

为什么单列：会议逐字稿不是普通文档 —— 它是语音转写产物，自带两类问题（转写噪音 + 说话人不明）， 而且它是原始记录，一个字都不能改。这两条决定它必须走另一套流程。 完整归档流程见 meeting-archive 技能第 4·5 步；这里只讲翻译侧。

三条与普通文档不同的要求

转写噪音怎么处理

翻完必须校验（不能省）

# ① 段数对得上
grep -c '^@说话人' 原文.md 产出稿.md
# ② 原文每一行都原样在产出稿里
while IFS= read -r line; do
  [ -z "$line" ] && continue
  grep -qF "$line" 产出稿.md || echo "❌ 缺失: ${line:0:80}"
done < <(grep -v '^@说话人' 原文.md)

实测（2026-09-28，115 段英文逐字稿）：抓出 2 处肉眼看不见的手误 —— 多一个逗号、少一个空格。 判据：能用一个数字验证的，就别用眼睛看。

第 3 步：落盘

放哪、叫什么

• 放在原文件同级目录或项目约定的资料目录
• 文件名：{原文件名}_中文对照版_{YYYYMMDD}.md
• 例：User ID Acknowledgement Form_中文对照版_20260917.md

文件头（必须有）

> 生成时间：{YYYY-MM-DD} | 最后更新：{YYYY-MM-DD}
> 所属：{组织/项目}
> 用途：{原文档名}中文对照 —— 内部理解用，非正式译本
> 翻译模式：完整翻译（1:1 忠实） ｜ 原文：{原文件路径}

文档结构

## 〇、一句话结论        ← 这份文档是什么、需要做什么（结论先行）
## 一、逐段翻译          ← 中英对照
## 二、阅读后的发现       ← 关键信息、条款、待确认项
## 三、翻译模式说明       ← 本次用的哪种（完整 / 脱敏 / 对照）
## 四、关联              ← 和哪些已有文档相关
## 版本历史              ← 设计文档强制（DOC-VER-001）

翻完必须做两件事

1. 打开给用户看 —— open "<落盘路径>"（macOS），别只给路径让他自己找
2. 说明翻译模式 —— 告诉用户这份是完整翻译还是脱敏翻译，能不能外发由他判断

翻译模式（默认完整，脱敏是可选项）

单一职责：本技能的本职是「忠实翻译」。保密是使用者的选择，不是翻译器的预设。

⚠️ 反面教训：把"密码/token 不进产出"写成铁律，会让翻译工具因为"安全"而交出一份残缺的翻译—— 缺了信息的翻译就是没完成工作。安全策略属于使用者的决策，不属于翻译器的默认行为。

翻译前问一次（此后记住偏好，不要重复问）：

呈现方式（同样可选）：中英对照 / 纯中文 / 纯原文

💡 偏好记忆：用户选过一次就记下来（项目 .claude/ 或用户配置），别再每次都问—— 重复询问是把成本转嫁给使用者。

敏感信息：唯一保留的底线

翻译产出本身不删减（那是使用者的选择）。但不主动扩散：

产出文档里写一节「翻译模式」说明本次用了哪种模式即可，不需要专门写"信息处理说明"—— 那是把内部约定暴露给读者。

排错

与「翻译」相关的能力扩展位

本技能是自建翻译能力的底座。要加自有的东西，往这几处放：

红线

• ❌ 不擅自脱敏 —— 默认完整翻译；要脱敏等使用者明确要求再做
• ❌ 不脑补 —— 提取失败就说失败，看不清就说看不清
• ❌ 不美化法律条款 —— 责任、义务、处罚类措辞直译
• ❌ 不把翻译产出里的敏感信息顺手抄到别处（CHANGELOG / 汇报 / 其他文档）—— 要用就回指原文档
• ✅ 翻完打开给用户看，并说明「能不能传阅」
• ✅ 读含密文档时主动提醒 —— 明文会进会话日志，建议用完移出工作目录