SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ppt-translator

ppt-translator

办公与效率

查看项目

更新于 10-16 04:09

技能介绍

用途

ppt-translator 是一个 PowerPoint 翻译技能，用于在翻译 .pptx 文件时保留全部格式，包括字体、颜色、间距、表格和对齐。它适用于以下场景：

  • 在语言之间翻译 .pptx 文件
  • 批量翻译目录中的多个演示文稿
  • 在翻译过程中保留幻灯片格式（尤其是中日韩 ↔ 英文）
  • 使用视觉语言模型对翻译后的演示文稿进行质量审计（--vision-audit），以发现文本溢出、截断、乱码字形、未翻译残留、重叠或对比度问题
  • 需要检查中间 XML 进行调试时

主要能力

  • 保留格式：翻译时保持字体、颜色、间距、表格和对齐不变。
  • 多提供商支持：支持 DeepSeek、OpenAI、Anthropic、Grok、Gemini 等 LLM 提供商。
  • 批量翻译：可对目录中的多个演示文稿进行批量翻译。
  • 视觉审计：可选使用 DeepSeek 视觉模型对重建后的幻灯片进行渲染检查，报告具体视觉缺陷，并按严重程度（高/中/低）分组。
  • 字体缩放：从紧凑语言（中文、日文、韩文）翻译为英文时，自动缩小字体（文本 70%，表格 80%）以防止固定尺寸文本框中的文本溢出。
  • 缓存：演示文稿中重复的字符串会被缓存，避免冗余 API 调用，适用于重复的页眉、页脚或术语。
  • 分块：长文本块在句子边界处智能拆分，以保持在 API 限制内并保持翻译质量。

使用方式

环境设置

首次使用前，设置环境：

# 进入脚本目录
cd .claude/skills/ppt-translator/scripts

# 创建虚拟环境并安装依赖
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

# 配置 API 密钥
cp example.env .env
# 编辑 .env 填入你的提供商 API 密钥

基本用法

cd .claude/skills/ppt-translator/scripts
source .venv/bin/activate

python main.py /path/to/presentation.pptx \
  --source-lang zh \
  --target-lang en

默认提供商为 DeepSeek 的 deepseek-v4-flash。

提供商配置

提供商 环境变量 默认模型
deepseek DEEPSEEK_API_KEY deepseek-v4-flash
openai OPENAI_API_KEY gpt-5.2-2025-12-11
anthropic ANTHROPIC_API_KEY claude-sonnet-4-5-20250514
grok GROK_API_KEY grok-4.1-fast
gemini GEMINI_API_KEY gemini-3-flash-preview

CLI 参考

选项 描述 默认值
--provider LLM 提供商：deepseek, openai, anthropic, grok, gemini deepseek
--model 覆盖提供商的默认模型 提供商默认
--source-lang 源语言 ISO 代码 zh
--target-lang 目标语言 ISO 代码 en
--max-chunk-size 每次 API 请求的字符数 1000
--max-workers 幻灯片提取的线程数 4
--keep-intermediate 保留 XML 文件用于调试 false
--vision-audit 翻译后，将每个重建的幻灯片渲染为图像，并使用 DeepSeek 视觉模型检查溢出、截断、乱码字形、未翻译文本、重叠或对比度问题。需要 DEEPSEEK_API_KEY 以及安装 LibreOffice + poppler (pdftoppm)。生成 {deck}_translated_vision_audit.md。 false
--vision-model --vision-audit 使用的视觉模型 deepseek-v4-flash-vision-exp
--vision-dpi 审计图像的渲染分辨率 100

输出文件

对于每个输入的 presentation.pptx，工具生成：

  • presentation_original.xml - 提取的源内容（除非 --keep-intermediate，否则删除）
  • presentation_translated.xml - 翻译后的内容（除非 --keep-intermediate，否则删除）
  • presentation_translated.pptx - 最终翻译后的演示文稿，格式完整
  • presentation_translated_vision_audit.md - 仅在使用 --vision-audit 时：视觉模型逐幻灯片的发现，按幻灯片分组，带严重程度（高/中/低）

常见工作流

翻译单个文件（中文 → 英文）：

python main.py deck.pptx --provider anthropic --source-lang zh --target-lang en

批量翻译目录：

python main.py /path/to/presentations/ --provider openai --source-lang ja --target-lang en

调试翻译问题：

python main.py deck.pptx --keep-intermediate --provider deepseek
# 检查生成的 XML 文件以查看提取/翻译的内容

使用特定模型：

python main.py deck.pptx --provider openai --model gpt-5-mini

使用 Gemini 翻译（成本效益）：

python main.py deck.pptx --provider gemini --source-lang ko --target-lang en

翻译并运行视觉审计：

python main.py deck.pptx --source-lang zh --target-lang en --vision-audit

重建演示文稿后，每个幻灯片被渲染为 PNG（LibreOffice headless → pdftoppm），并与该幻灯片的预期翻译文本一起发送给 deepseek-v4-flash-vision-exp。模型将渲染结果与预期内容进行比较，并报告具体的视觉缺陷。之后阅读 {deck}_translated_vision_audit.md，并在交付前修复任何高严重性的发现（例如通过缩短文本或放大文本框）。

对已翻译的演示文稿不需要仅审计重跑——审计在 --vision-audit 运行结束时自动运行，审计失败永远不会中止翻译本身。

支持的语言

使用标准 ISO 639-1 语言代码：

代码 语言
zh 中文（简体）
en 英语
ja 日语
ko 韩语
es 西班牙语
fr 法语
de 德语
pt 葡萄牙语
ru 俄语
ar 阿拉伯语

适用场景

  • 需要将中文、日文、韩文等演示文稿翻译为英文，同时保持原有排版和格式。
  • 批量处理多个演示文稿文件。
  • 对翻译质量有较高要求，需要视觉审计来发现排版问题。
  • 需要调试翻译过程，检查中间 XML 内容。

限制

  • 视觉审计需要额外安装 LibreOffice 和 poppler (pdftoppm)，并且始终需要 DeepSeek API 密钥，即使使用其他提供商进行翻译。
  • 视觉审计在 macOS 26 + LibreOffice 25.x 组合上可能崩溃，需升级 LibreOffice。
  • 翻译质量依赖于所选 LLM 提供商和模型。
  • 字体缩放是自动的，可能不适用于所有布局，需人工检查。
  • 需要有效的 API 密钥和足够的配额。

故障排除

  • “API key not found”：确保 scripts 目录中的 .env 文件包含正确的环境变量，如 OPENAI_API_KEY=sk-... 或 ANTHROPIC_API_KEY=sk-ant-...。
  • 格式看起来不对：使用 --keep-intermediate 检查 XML 文件；检查源演示文稿是否有异常格式；尝试不同的提供商。
  • 翻译不完整：检查提供商的 API 速率限制；尝试减小 --max-chunk-size 以处理非常长的文本块；确保 API 密钥有足够配额。
  • “Visual audit skipped: ... tools that were not found”：视觉审计需要 LibreOffice (soffice) 和 poppler (pdftoppm)。macOS 安装：brew install --cask libreoffice && brew install poppler；Debian/Ubuntu：apt install libreoffice poppler-utils。如果 LibreOffice 本身在启动时崩溃（在某些 macOS 26 + LibreOffice 25.x 组合上出现），升级它：brew upgrade --cask libreoffice。
  • “The visual audit requires a DeepSeek API key”：审计始终调用 DeepSeek 的视觉端点，无论翻译提供商是什么，因此即使使用其他提供商翻译，也必须设置 DEEPSEEK_API_KEY。

脚本参考

scripts/ 目录包含：

  • main.py - 入口点
  • requirements.txt - Python 依赖
  • example.env - 环境变量模板
  • ppt_translator/ - 核心翻译模块
    • cli.py - CLI 参数解析
    • pipeline.py - PPT 提取和重新生成
    • translation.py - 分块和缓存
    • providers/ - LLM 提供商实现
    • vision_audit.py - 幻灯片渲染（LibreOffice + pdftoppm）和 DeepSeek 视觉模型 QA