# Pptx Bilingual Translate

> 把中文 PPT/PPTX 课件整章翻译成「英文版 + 中英对照版」两份成品，并自动重排版面、处理 WPS 隐藏内容、防止文字溢出。当用户要求翻译 PPT / 幻灯片 / 课件 / 教材、做英文版 PPT、做中英双语对照 PPT、把 pptx 译成英文，或提到 WPS 隐藏文字、mc:AlternateContent、翻译后文字溢出、图内文字翻不了时使用。Translate a Chinese PowerPoint deck into an English deck plus a Chinese/English bilingual deck, rebuilding the layout so nothing overflows. 只要任务涉及把幻灯片在中英之间翻译，哪怕用户只说「帮我把这个 ppt 翻一下」，也要先加载本技能——直接用 python-pptx 逐个 run 替换文字，几乎必…

- **Type:** Skill
- **Install:** `agentstack add skill-xingzaozhan43-ultimate-pptx-bilingual-translate-pptx-bilingual-translate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Xingzaozhan43-ultimate](https://agentstack.voostack.com/s/xingzaozhan43-ultimate)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Xingzaozhan43-ultimate](https://github.com/Xingzaozhan43-ultimate)
- **Source:** https://github.com/Xingzaozhan43-ultimate/pptx-bilingual-translate

## Install

```sh
agentstack add skill-xingzaozhan43-ultimate-pptx-bilingual-translate-pptx-bilingual-translate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/` 全部拷进去），产物留在原地便于回溯。

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

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

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

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

```bash
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. 提取隐藏内容

```bash
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`。

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

### 4. 排版重建

```bash
python build_full.py
```

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

### 5. 隐藏内容后处理

```bash
python process_hidden.py
```

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

### 6. 隐藏块缩放收敛

```bash
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. 校验

```bash
python run_checks.py
```

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

### 8. 真的看一眼

```bash
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](https://github.com/Xingzaozhan43-ultimate)
- **Source:** [Xingzaozhan43-ultimate/pptx-bilingual-translate](https://github.com/Xingzaozhan43-ultimate/pptx-bilingual-translate)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xingzaozhan43-ultimate-pptx-bilingual-translate-pptx-bilingual-translate
- Seller: https://agentstack.voostack.com/s/xingzaozhan43-ultimate
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.