本地化信息图PDF（保留原稿艺术效果）
生成一个设计PDF的翻译版本，该版本在视觉上与原始版本完全相同，只是所有运行文本都替换为目标语言。工作原理：栅格化页面，擦除源文本，然后将翻译后的文本合成回原始坐标位置——艺术元素（照片、图表、渐变、图标、Logo）不会被重新生成。
为什么使用此流程（请先阅读）
设计导出的PDF通常会将可见文本存储为矢量轮廓（文本转曲线）或Type3字形——它不可编辑，也没有干净的“替换文本”方法。但这些PDF几乎总是同时带有一个隐藏的、可搜索的文本层，其词框与可见文本的像素对齐。该层免费提供了精确的位置/大小信息。因此：不要尝试编辑文本，也不要使用生成式图像模型来“重绘”背景——这会更改艺术元素且无法实现像素忠实。相反，采用覆盖和叠加的方法：擦除每个源字形运行，然后在原位重绘译文。背景保持字节忠实。详细原理和失败模式请参见 references/pipeline.md。
工作流程（按顺序从技能的 scripts/ 目录运行脚本）
选择一个工作目录（默认为 loc_work）。所有脚本都接受 SOURCE.pdf [OUTDIR] [PAGE] 参数。
-
分析 —
01_analyze.py SOURCE.pdf OUTDIR确认文本的存储方式，列出嵌入图像，渲染页面。查看渲染结果，并注意任何嵌入图表/Logo/照片图像中的文本（这些文本不会出现在文本层中，必须作为manual_labels处理）。 -
提取 —
02_extract.py SOURCE.pdf OUTDIR（环境变量LOC_KEEP='brandA|brandB'用于在源语言中保留更多字符串）。生成units.json（每个物理文本行一个条目，包含bbox/颜色/大小）和translator_source.txt（一个带ID标签的可读负载）+half_*.png。 -
翻译 — 调度一个翻译代理。将
translator_source.txt和half_0/1.png提供给它。它必须写入OUTDIR/translation.json = {"<id>":"译文", ...}，覆盖每个ID（对于KEEP-AS-IS的ID，原样输出）。使用references/agent-prompts.md中的提示。 -
覆盖（仅在需要时） — 为自动引擎无法看到的文档特定部分编写
OUTDIR/overrides.json：嵌入图像中的文本（manual_labels）、细描边控件（如药丸/徽章）内的文本（solid_fill_labels）、居中标签区域（centered_id_ranges）以及drop_ids。模式+如何测量坐标：references/overrides.md。大多数简单的传单不需要覆盖；图表密集的文档需要少量覆盖。 -
合成 —
03_compose.py SOURCE.pdf OUTDIR→final_zh.png。这是确定性引擎（背景重建+统一大小的重绘）。每个文档无需调整参数。 -
PDF+裁剪标记 —
04_pdf.py SOURCE.pdf OUTDIR OUT.pdf→ 生成PDF以及zh_L/zh_R.png供质量检查。 -
审查与迭代 — 调度一个审查代理，将
zh_L/zh_R.png与half_0/1.png进行比较（提示在references/agent-prompts.md中）。通过编辑overrides.json/translation.json修复发现的问题，并重新运行03→04。重复直到干净。典型问题及其修复方法在references/pipeline.md中列出。
三个角色循环（翻译 → 合成 → 审查）模拟了人工本地化团队；运行审查1-2次可捕获长尾问题（残留源文本、大小不匹配的文本块）。
引擎自动处理的内容（无需配置）
- 浅色文本在深色背景上以及深色文本在浅色背景上的面板（选择正确的背景颜色）。
- 纯色面板、平滑渐变和照片背景（按区域选择填充或内绘画）。
- 没有可见字形的“幽灵”文本层条目（自动跳过——从不绘制）。
- 项目符号被吞入第一行框中的项目符号列表（自动重新对齐）。
- 字体大小：保留原始大小，按块统一，因此包装段落/引用不会显得参差不齐。
默认设置与要求
- Python：
pymupdf (fitz)、numpy、opencv-python (cv2)、Pillow。 - CJK字体默认
Hiragino Sans GB.ttc（macOS；W3常规索引0 / W6粗体索引2）。可通过overrides.json中的"font"覆盖其他语言/字体。 - 渲染缩放默认6.0（≈432 dpi）。迭代时降低到4以提升速度；打印时提高。
- 默认保留源语言的：URL、电子邮件、品牌/产品商标、Logo嵌入文本、裸数字/单位、专有名称。由翻译决定；保留正则表达式预先标记明显的部分。
参考文件
references/pipeline.md— 原理、擦除策略决策树以及常见视觉缺陷及其精确修复方法目录（条纹、残留、破损药丸、尺寸塌陷）。references/agent-prompts.md— 即用型翻译和审查代理提示。references/overrides.md—overrides.json模式以及如何测量图表/药丸坐标。