PPT 翻译为英文 (PPT Translate to English)

将 PowerPoint 演示文稿中的所有中文内容翻译为英文，完整保留所有格式。

核心能力

• 全量覆盖：幻灯片标题、正文、艺术字(WordArt)、表格单元格、图表(标题/分类/系列名)、SmartArt、幻灯片备注、幻灯片母版/版式
• 格式零损失：字体名称、字号、粗体/斜体/下划线、文字颜色、艺术字特效(文本变形、渐变填充、文字描边、阴影/发光)、段落对齐/间距/项目符号、形状位置/大小/旋转、超链接 —— 全部原样保留
• 艺术字特别保护：仅替换 <a:t> 文本内容，<a:rPr> 中的所有特效属性原封不动

环境要求

• Python 3.9+（推荐 managed Python 3.13）
• python-pptx 库（pip install python-pptx，或使用清华镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple）
• lxml 库（python-pptx 依赖，自动安装）
• 无需安装 WPS Office 或 Microsoft Office

技术原理

翻译安全性的核心：python-pptx 的 run.text = "new text" 仅修改 XML 中 <a:r> 元素内的 <a:t> 子元素（文本内容），而 <a:rPr>（运行属性，存储所有字体和特效信息）完全不受影响。

艺术字的特效（文本变形 prstTxWarp、渐变填充 gradFill、描边 ln、阴影 effectLst）全部存储在 <a:rPr> 或 <a:bodyPr> 中，因此翻译后视觉效果完全一致。

详见 references/wordart_and_formatting.md。

工作流程（3 步）

第 1 步：安装依赖

# 确保 managed Python venv 存在并安装依赖
PY="C:/Users/86176/.workbuddy/binaries/python/envs/default/Scripts/python.exe"
"$PY" -m pip install python-pptx -i https://pypi.tuna.tsinghua.edu.cn/simple

如果 venv 不存在，先创建：

"C:/Users/86176/.workbuddy/binaries/python/versions/3.13.12/python.exe" -m venv "C:/Users/86176/.workbuddy/binaries/python/envs/default"

第 2 步：提取文本

SKILL_DIR="C:/Users/86176/.workbuddy/skills/ppt-translate-to-english"
PY="C:/Users/86176/.workbuddy/binaries/python/envs/default/Scripts/python.exe"

"$PY" "$SKILL_DIR/scripts/ppt_translate.py" extract "input.pptx" -o text_items.json

输出 text_items.json 包含：
- 每个文本项的 id、original(原文)、has_chinese(是否含中文)、paragraph_text(段落全文，提供翻译上下文)
- 位置信息：slide_index、shape_id、target(shape/table_cell/chart_title/chart_category/chart_series/smartart/notes)、paragraph_index、run_index
- 格式信息：is_wordart(是否艺术字)、font_info(字体快照)
- 统计摘要：total_slides、total_items、chinese_items

脚本会在终端打印所有含中文的文本项列表，方便核对。

第 3 步：翻译并应用

翻译：读取 text_items.json，将所有 has_chinese: true 的项的 original 文本翻译为英文，生成翻译映射文件 translations.json：

{
  "0": "Quarterly Report",
  "1": "Innovation Driven Development",
  "3": "Data Analysis",
  "5": "Thank You"
}

翻译指导原则：
- 键为文本项 id（字符串），值为英文翻译
- 只需翻译 has_chinese: true 的项，不含中文的项跳过
- 参考 paragraph_text 理解上下文，确保翻译准确
- 参考 slide_title 理解该文本所在幻灯片的主题
- 艺术字(is_wordart: true)翻译尽量简洁，避免文本过长溢出形状
- 多 run 段落：每个 run 独立翻译，翻译结果应作为该 run 的片段，拼接后形成完整通顺的英文句子
- 数字、日期、专有名词(如公司名)通常不需要翻译

应用翻译：

"$PY" "$SKILL_DIR/scripts/ppt_translate.py" apply "input.pptx" text_items.json translations.json -o translated_output.pptx

可选参数 --update-lang：将翻译后的 run 的 lang 属性从 zh-CN 改为 en-US（不改变视觉格式，但有助于拼写检查和字体选择）。

输出文件 translated_output.pptx 可用 WPS Office 或 Microsoft PowerPoint 打开。

翻译文件格式

支持三种格式（任选其一）：

格式 A — 简单映射（推荐，最简洁）：

{"0": "Quarterly Report", "1": "Innovation"}

格式 B — 完整项列表：

[
  {"id": 0, "translated": "Quarterly Report"},
  {"id": 1, "translated": "Innovation"}
]

格式 C — 带位置信息的完整 JSON（从 text_items.json 修改而来）：

{
  "items": [
    {"id": 0, "original": "季度报告", "translated": "Quarterly Report", ...},
    ...
  ]
}

使用格式 A 或 B 时，apply 命令需要 text_items.json 参数来获取位置信息。

覆盖范围

注意事项

1. 原文件不被修改：apply 命令总是输出新文件
2. 文本溢出：英文通常比中文长，翻译后可能出现文本溢出形状边界的情况。脚本不会自动调整字号（以保留格式），如需调整请手动处理
3. SmartArt：通过 ZIP 级 XML 操作处理，需要 PPTX 文件未被密码保护
4. 图表外部数据：如果图表引用外部 Excel 工作簿的数据，分类名和系列名可能无法通过 XML 修改
5. 多 run 段落：当一个段落有多个不同格式的 run 时，每个 run 独立翻译。翻译时应参考 paragraph_text 确保拼接后通顺

故障排除