Pptx Bilingual Translate

PPT 中英翻译流水线

一次可靠地交付两份成品：英文版（全英）与中英对照版（中文黑、英文蓝，逐段对照）。

方法论来自一套 900 余页、11 个章节的半导体封装教材 PPT 的实战翻译，全部坑点已固化进 scripts/ 与 references/。不要从零写脚本——scripts/ 是可直接运行的完整工具链，照抄进工作目录即可。

为什么不能"直接替换文字"

新手做法是 python-pptx 遍历 run、把中文换成英文、保存。这条路必然失败，原因有四：

| 陷阱 | 后果 | |---|---| | 英文比中文长约一倍，而文本框是固定的 | 满页正文出血到页外 / 压住下方图片 | | PowerPoint 的 normAutofit（"溢出时缩排文字"）在导出与非 PowerPoint 渲染时不生效 | 你以为会自动缩小，实际被裁掉 | | WPS 把大量内容藏在 ` 里，**python-pptx 完全看不见** | 整页正文、整张表格原样留着中文 | | tf.clear() 保留首段的 pPr` | 原来带自动编号的单元格渲染出幽灵 "1." |

所以字号必须自己算好写死，版面必须按邻居实测重排，隐藏内容必须改原始 XML。

开工前先确认三件事

1. 要哪几版？ 默认两版都出。如果只要英文版，对照版的所有取舍（字号更小、段落翻倍）就不必迁就。
2. 满页怎么办？ 默认「自动缩小字号保持一页」，不拆页。若用户希望拆页，整条流水线的排版策略要重谈。
3. 术语表。 教材里的专有名词（工艺名、器件名、厂商技术名）先问清楚，或从已交付的同系列章节沿用，

不要每章各译一套。

工作流

每一步都在独立的工作目录里跑（源文件 + scripts/ 全部拷进去），产物留在原地便于回溯。

mkdir 工具脚本-第X章 && cd 工具脚本-第X章
cp /path/to/源课件.pptx source.pptx
cp /scripts/* .

Windows 上先设两个环境变量，否则中文 dump 会炸出一堆假的编码错误：

set PYTHONUTF8=1 && set PYTHONIOENCODING=utf-8

1. 侦察：这份 deck 到底有多少活

python audit.py && python scan_raw.py

audit.py 清点可见文本与表格，写出 audit.json（整条流水线的键就来自这里）。 scan_raw.py 读原始 XML，回答四个决定工作量的问题：哪些页有 mc:AlternateContent、 ` 数是否与可见表数对得上、有没有公式里藏中文、页序是否等于 slideN.xml` 编号。

把 scan_raw.py 打印的 AC_SLIDES / AC_TABLE_SLIDES 抄进 config.py，同时填好 STEM。

> 一章的真实体量看这两个数：可见文本项数、总字数。85 页 / 238 项 / 18000 字是一个典型章节。

2. 提取隐藏内容

python extract_choice.py     # 仅当 AC_SLIDES 非空

写出 choice_audit.json：每个隐藏块的 Choice 与 Fallback 两侧文本、段落划分、矩形与字号。 这一步不能省——它同时给排版代码提供了隐藏块的矩形，否则可见正文会被排到隐藏文字上面。 细节见 references/hidden-content.md。

3. 翻译

把译文写进 tr_p1.py、tr_p2.py……（每份 40–60 页），键是 "页:sid" 或 "页:sid:行:列"。 隐藏块的译文另写在 ac_draft.py。源文中文本身的错误写进 cn_fix.py。 译写规范（段落数必须守恒、什么该改什么不该改、哪些东西根本翻不了）见 references/translating.md。

python check_coverage.py     # 每一项都有译文，且没有拼错的孤儿键
python check_paras.py        # 中英段落数逐项对齐
python gen_acpara.py         # ac_draft.py -> ac_para.py（按内容而非序号配对）

4. 排版重建

python build_full.py

按框的位置、高度与原始字号把每个形状分成 title / body / list / column / caption / in-place 六类， 各用一套策略重排并显式写死字号。build_full.py 顶部有六张 per-deck 覆盖表， 每张都注明了"看到什么现象才需要动它"。分类判据与策略详见 references/layout.md。

5. 隐藏内容后处理

python process_hidden.py

把 _EN_raw / _BI_raw 当 zip 打开，直接改 slide XML，写出两份交付文件。 三种策略（逐 run REPL、整段 AC_PARA、公式 MREPL）的取舍见 references/hidden-content.md。

6. 隐藏块缩放收敛

python ac_fit.py             # 报告每个隐藏块需要的字号因子
python apply_scale.py        # 把因子折进 process_hidden.py 的 SCALE
python process_hidden.py     # 重跑
python ac_fit.py             # 直到全部 fit=1.00

隐藏块没有 normAutofit，超出就是超出。通常两轮收敛。

7. 校验

python run_checks.py

一次跑完 coverage / paragraphs / residual / overflow / on-picture / ac-fit 并给出汇总。 这些是估算，会有假阳性（旋转标签、纯拉丁标题），它们的作用是告诉你该看哪几页。 判读方法见 references/verification.md。

8. 真的看一眼

powershell -ExecutionPolicy Bypass -File export_png.ps1 -Deck "\成品_英文版.pptx" -OutDir png_en
python ink.py png_en         # 每页最低墨迹位置，抓被裁掉的行

用本机 PowerPoint 逐页导 PNG。静态检查抓不到"文字压在深色照片上看不清"这类问题， 而 ink.py 能在不逐页看图的前提下先筛出可疑页。声称完成前必须真的渲染过。

参考文档

| 文件 | 什么时候读 | |---|---| | references/pipeline.md | 命令速查、目录结构、每一步的产物与失败信号 | | references/layout.md | 排版分类器与六种策略；改 build_full.py 之前必读 | | references/hidden-content.md | mc:AlternateContent 的一切；有隐藏内容就读 | | references/translating.md | 译写规范、术语、cn_fix.py 的边界、翻不了的东西 | | references/verification.md | 各项检查的含义、已知假阳性、渲染核对 | | references/pitfalls.md | 十一章积累的具体坑点清单；遇到怪现象先在这里搜 |

交付

同时交付两份 pptx 与一份说明，说明里必须包含：

• 翻不了的部分：位图里的中文标注、整体是图片的表格、公式里的中文下标——逐条列出页码，

不要让读者自己发现。

• 改过的原文：cn_fix.py 里每一条，附理由。技术性改写（改术语、改数值）要请作者复核。
• 存疑未改的地方：数量级不合的数据、自相矛盾的图号，照原文保留并提请核对。

保留整个工作目录（脚本 + audit.json + choice_audit.json + 译文文件）。 下一章 95% 的工作是复用它。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Xingzaozhan43-ultimate
• Source: Xingzaozhan43-ultimate/pptx-bilingual-translate
• License: MIT

Install and usage instructions live in the source repository linked above.