doc-translatelisted
Install: claude install-skill xingtu1996/xingtu-skills
# 文档翻译(doc-translate)
## 你要解决的事
用户给你一份文档(常是外语合同、表单、说明书、报价单),他要的是三件事:
1. **看懂** —— 关键信息提出来(谁发的、给谁的、要干什么、有什么条款)
2. **中文对照** —— 逐段翻译,能和原文对照着看
3. **留档** —— 落盘成 Markdown,能传给同事、能进知识库
> 本技能是**科码自建技能**。未来要在翻译这件事上叠加自有的口径/术语表/模板,都在这里长。
---
## 三条铁律
1. **先用脚本提取,别硬读文件** —— Direct Read 一个 PDF 会直接报错(缺 `pdftoppm`),而且拿不到结构化分页。**脚本 20 秒搞定的事,不要在工具选择上试错**。
2. **翻译就是翻译** —— 默认 **1:1 完整翻译**,**不因"安全"擅自删减**。脱敏是**使用者的可选要求**,不是默认行为——擅自脱敏 = 交出一份残缺的翻译,等于没完成工作。
3. **提取不到就说提取不到** —— 扫描件、无文本层、字体乱码,如实标注,**不要脑补内容**。翻译错了比没翻译更危险。
---
## 第 0 步:提取文本(全自动,别问用户)
```bash
bash <本技能目录的绝对路径>/scripts/extract-doc.sh "<文件绝对路径>"
```
**先把文件复制/保存到本地磁盘**——云盘占位符文件(`.icloud`、未下载的 OneDrive 项)会读不到内容。
脚本会**自动探测工具链,缺什么装什么**:
| 格式 | 走什么 | 首次成本 |
|------|--------|---------|
| PDF | 有 `pdftotext` 用 `pdftotext`(最准),没有退回 `pypdf` | 首次自动建 venv 装 pypdf,约 20 秒,之后常驻 |
| docx / xlsx / pptx | Python 标准库解 zip + XML(**零依赖**) | 无 |
| txt / md / csv / json / xml / log | 直接读 | 无 |
| 图片(png/jpg/…) | **不走脚本** —— 用 AI 视觉能力直接读图,比 OCR 好 | 无 |
**先跑一次环境自检**(想知道为什么失败时):
```bash
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。**脚本里已经把这些坑都绕开了,直接用就行。**
### 提取完先看这两样
| 看什么 | 为什么 |
|--------|--------|
| **页数**(脚本会打印) | 判断"这是不是我以为的那份文档"。**同名不同物的两份文件,靠页数一眼分开**——例:`User Access Request Form` 3