PDF 中越双语互译（原样重排）
一句话：给它 PDF，还你 PDF —— 不重排版面、不转格式、不输出对照表，
译文直接写回原版式，打开就是可打印的双语文件。
使用案例
案例 1｜越南施工进度计划译中（高频）
> 用户：把这份 PDF 翻译成中越双语，格式不要变。附件 Tien do tong the.pdf
（MS Project 导出的横道图，越南语）。
→ 输出 Tien do tong the_中越双语.pdf：横道图、表格线、颜色、图例全部保留，
每行「越语原文 + 中文译文」。
案例 2｜中文技术表格译越
> 用户：这份中文的桩基检验报告要发给越方，帮我做成双语 PDF。
→ 输出 桩基检验报告_中越双语.pdf：表格结构不变，原文在前、译文在后。
案例 3｜多页大文件批量处理
> 用户：Tien do chi tiet.pdf 有 110 页，都要双语。
→ 同一套流水线，去重后待译条目骤减（110 页仅数百条唯一文本），
术语库命中后 pending 自动收缩，约 1 分钟出稿。
能力边界
| 项 | 说明 |
|---|---|
| 输入 | 有文字层的矢量 PDF（Project 导出进度计划、报告、表格等） |
| 输出 | <原名>_中越双语.pdf，与原件同页数同版式 |
| 翻译方向 | 自动识别；也可 --direction vi2zh｜zh2vi 强制 |
| 双语形式 | 每个单元格/段落「原文在前、译文在后」，多行块逐行配对 |
| 保留内容 | 表格线、横道图、色块、图例、图片、页面旋转方向，一概不动 |
| 缩放策略 | 译文放不下时块内整体微缩（下限约 0.58 倍），尽量不溢出 |
| 不译内容 | 数字、日期、桩号、代号（MSS/BĐ/SĐ5）、承包商代号堆、页脚，自动跳过 |
| 原文件 | 只读不写，输出永远是新文件 |
| 不支持 | 扫描件（无文字层）需先 OCR；不处理加密 PDF |
四步工作流
第 1 步：环境体检（首次或报错时）
python scripts/pdf_translate.py env
输出 pymupdf 版本、字体路径、四个旋转角度的方向向量、术语库规模。
缺中文字体会直接报错，需安装黑体或 Noto Sans CJK。
第 2 步：prepare —— 提取 + 术语库自动命中
python scripts/pdf_translate.py prepare "D:/xxx/文件.pdf"
产出 job/<文件名>/：
- pending.json —— 待译清单，每条带出现次数、页码和 hint（历史相似句对，相似度 1.0 可直接抄）
- auto.json —— 术语库/正则/历史记忆自动命中的译文
- blocks.json —— 布局缓存（apply 直接复用，不用重新解析）
统计行会显示：文本块数、自动命中数、待译数。
若报「未提取到任何文本」，该 PDF 是扫描件（无文字层），需先 OCR。
第 3 步：翻译 pending → 写 translations.json
读 pending.json，逐条翻译，写成：
{ "原文A": "译文A", "原文B": "译文B" }
保存为 job/<文件名>/translations.json。要点：
- 优先抄 hint 相似度 ≥0.95 的历史译法（改数字/墩号即可），术语全篇一致
- 专名（公司名 Yuanda、桥名 Rạch Đỉa、代号 SĐ5）保留原文不译——不写进 translations 即可
- 数字、日期、桩号照抄进译文，不换算格式
- 键必须与 pending 里的 text 完全一致；line: true 标记表示该块按逐行模式翻译，可忽略也可单独译
第 4 步：apply —— 生成双语 PDF + 抽查
python scripts/pdf_translate.py apply "D:/xxx/文件.pdf"
# 默认输出到源文件同目录 <原名>_中越双语.pdf
python scripts/pdf_translate.py render 输出.pdf --pages 0,1,40 -o work/check
apply 自动加载：auto.json + translations.json（+ 可选 --map 额外表）。
未译文本会列出清单——专名类忽略即可，成句的一定要补译重跑。
抽查渲染图：逐页看有无重叠、漏译、方框。
收尾：译文沉淀进术语库
python scripts/glossary_tool.py import-map "job/<文件名>/translations.json"
下次遇到同项目/同模板的 PDF，prepare 直接命中，pending 骤减。
命令速查
| 命令 | 作用 |
|---|---|
env |
字体 / pymupdf / 方向探针 / 术语库规模体检 |
prepare <pdf> |
提取块 → 自动翻译 → 输出 pending |
apply <pdf> [-o 输出] |
读译文生成双语 PDF |
render <pdf> --pages 0,1 --dpi 110 -o 目录 |
渲染抽查页 |
--direction vi2zh｜zh2vi |
强制方向（默认 auto：越南语多→译中） |
--map 表.json |
额外译文表（优先级高于 auto） |
--job 目录 |
自定义 job 目录（默认按文件名建） |
术语库维护见 glossary_tool.py（stats / find / add / remove / import-map / check）。
双层术语库
| 库 | 位置 | 用途 | 会被覆盖？ |
|---|---|---|---|
| 内置库 | assets/glossary.json |
通用施工/桥梁术语 + 模板句正则 + 152 词表 | 技能升级时 |
| 本地库 | ~/.pdf-zh-vi-translate/glossary.user.json |
项目专名、日常沉淀 | 不会 |
翻译优先级：exact 整串 → 大小写不敏感 → patterns 正则 → 历史句对记忆（seed_pairs）→ pending。
assets/seed_pairs.json 是历史句对库（越南桥梁项目），suggest 用它给 hint，不要手工编辑。
已固化的工程约定（来自实测）
- 中文用黑体、越南语用 Times New Roman（粗体 timesbd），混排自动按字符切换
- 页面任意旋转（0/90/180/270）都支持：方向向量由探针实测，不靠猜
- 译文优先「塞缝」（原行距放得下就不挤别的行），塞不下才推挤后续行
- 换行截断的半句不进行级待译清单；「表头词 + 代号堆」的单元格自动跳过
- 扫描件无文字层 → prepare 直接报错，别硬跑
- 一次处理一个 PDF（job 目录按文件名隔离；术语沉淀建议串行）
排障
| 现象 | 处理 |
|---|---|
| 中文显示方框 | env 里 cjk font 是否存在；缺黑体换 Noto Sans CJK / 文泉驿 |
| 越语变音符变方框 | 中文段被塞进 Times——查 insert_run 的分段逻辑是否被改 |
| 译文与下一行重叠 | 该块 avail 估大了；看 blocks.json 的 avail/band，多是网格探测失败 |
| pending 里大量数字串 | skippable 规则被绕过；确认文本里是否混了小写字母 |
| 110 页跑了 1 分钟+ | 正常（apply 约 1 分钟/110 页）；prepare 只要 ~8 秒 |
| 译文表没生效 | apply 会 norm 键（空白折叠）；确认 JSON 无重复键被覆盖 |
| CLI 报缺 pymupdf | pip install pymupdf |
更多坑位见 references/environment.md。
changelog
- 1.0.0 —— 首个版本：原地双语重排、自动方向/旋转识别、网格探测、逐行双语排版、
双层术语库、488 条越南桥梁项目历史句对、代号堆过滤。
