tristan-mcinnis/PPT-Translator-Formatting-Intact-with-LLMs skill 本地安装使用教程(2026新手版)

先别把它想成那种「打开PPT点一下就自动翻完」的桌面软件——这仓库其实是给Agent调用的PPT翻译工具：外层套了个Claude Agent Skill，真正干活的是里面的Python CLI。它会把PPT/PPTX里的文本、表格抽出来，丢给DeepSeek、OpenAI、Anthropic、Grok、Gemini这类大模型翻译，再尽量把字体、颜色、对齐、表格版式原样塞回去。

新手最容易踩俩坑：要么只复制了SKILL.md，没装scripts里的依赖；要么依赖装好了，却没给选的模型服务商配API Key。这不是离线翻译器，翻译肯定要调你选的模型服务。想先测本地环境的话，先跑帮助命令和测试就行。

图 1：先瞅一眼目录里有没有SKILL.md和scripts文件夹——少了scripts，Agent就算看得懂说明也跑不动翻译脚本。

装到哪？得看你用哪个宿主

要是你用的是支持Anthropic Skills的Claude Code这类宿主，按仓库README说的，把整个.claude/skills/ppt-translator/目录复制到目标项目的.claude/skills/下面就行。注意啊——是整个目录，不是只拿个SKILL.md。目录里自带scripts、requirements.txt、example.env还有ppt_translator代码，少复制一样都容易变成「Agent嘴上说会翻译，实际找不到脚本」的尴尬情况。

要是你想在Codex、ChatGPT、Copilot或者Gemini里用，别默认这些环境会自动加载.claude/skills。更稳的办法是把它当普通Python CLI用，或者在对应宿主里手动把SKILL.md的说明和脚本路径接进工作流。这个小坑挺多人踩：同样叫skill，不代表所有Agent客户端的本地加载机制都一样。

Python环境就按scripts目录装，别在仓库根目录瞎折腾

先进到.claude/skills/ppt-translator/scripts目录里，再建虚拟环境。命令很常规：python3 -m venv .venv；macOS或者Linux就用source .venv/bin/activate；然后pip install -r requirements.txt。Windows PowerShell的话用.venvScriptsactivate。仓库README写的是Python 3.10+，我自己用系统Python3.9也能跑通测试，但新手别拿3.9当推荐环境——后面google-auth这类依赖已经会提示3.9生命周期的问题了。

图 2：依赖装完先跑个pip check。像这样显示没有坏依赖，就说明openai、anthropic、google-genai、python-pptx、python-dotenv还有pytest这些基础包都已经在虚拟环境里了。

路径这儿也提个醒：PPT文件路径里带空格、中文或者括号的话，Python本身一般能处理，但终端复制命令很容易漏引号。新手第一次试跑，建议把样例PPT放在全英文的短路径里，比如~/ppt-test/deck.pptx。还有旧式.ppt别硬上——虽然CLI参数说明里写的是支持PPT/PPTX文件或目录，但python-pptx主要适配2007+的.pptx；老文件先用PowerPoint或者WPS另存为.pptx，能少碰好多奇怪报错。

密钥只填你要用的服务商就行，Gemini这儿有个文档小坑

把example.env复制成.env，只填你要用的那个服务的密钥就够了：OpenAI填OPENAI_API_KEY，Anthropic填ANTHROPIC_API_KEY，DeepSeek填DEEPSEEK_API_KEY，Grok填GROK_API_KEY。Gemini要特别注意：当前代码读的是GOOGLE_API_KEY，但README表格里写的是GEMINI_API_KEY——新手要是照着表格填GEMINI_API_KEY，脚本照样会报Gemini缺密钥。

DeepSeek和Grok都有base URL的变量，example.env里DeepSeek默认是https://api.deepseek.com，Grok默认是https://api.x.ai/v1。要是只用OpenAI，不用把其他服务商的空变量都补上，空着没事——脚本只会检查你本次--provider选的那一个。

图 3：没密钥的话，脚本会卡在校验服务商配置这一步，甚至还轮不到检查PPT路径。看到这个报错先补.env，别上来就怀疑文件路径有问题。

第一次先做小测试，跑通再上正式文件

装完依赖，先在scripts目录跑.venv/bin/python main.py --help。能看到--provider、--source-lang、--target-lang、--max-chunk-size、--max-workers、--keep-intermediate这些参数，就说明入口脚本和依赖至少都加载起来了。仓库还带了pytest测试，我本地跑是8 passed；这一步不代表翻译API能用，但能把「依赖没装好、模块导入失败、脚本入口找不到」这类低级问题先排掉。

图 4：帮助命令能正常显示服务商列表，测试也能过，再往下试翻译才靠谱。

真要翻译的话，先从一两页的样例PPT开始，别一上来就扔几十页的正式方案。命令可以这么写：.venv/bin/python main.py /path/to/deck.pptx --provider openai --source-lang zh --target-lang en --max-workers 2。README示例里max-workers是4，代码默认也是4；素材少的时候没问题，但要是PPT很大或者账号限速明显，先降到2更稳。文本多的页面还可以把--max-chunk-size从默认的1000调小一点，牺牲点速度，换更少的请求失败。

跑通后重点盯三个文件：deck_original.xml、deck_translated.xml、deck_translated.pptx。前两个方便你核对抽出来的原文和译文，最后那个才是能给同事看的PPTX。要是加了--keep-intermediate参数，还会保留更细的slide_*.xml，适合排查某一页为啥没翻好。别只盯着终端最后一行看，PPTX文件有没有生成、大小正不正常、能不能用PowerPoint打开，这三个信号才实在。

常见卡点按这个顺序查，省时间

1. 宿主没识别skill：检查.claude/skills/ppt-translator/是不是放在目标项目下面，目录名对不对，重启或者重新加载宿主再试。

2. 命令能跑但翻译前就报密钥错：先看.env是不是在scripts目录或者当前运行目录，能被load_dotenv找到，再确认变量名和你选的--provider对得上。

3. Gemini一直说缺key：当前代码读的是GOOGLE_API_KEY，不是README表格里的GEMINI_API_KEY。

4. 翻译中途失败：先把--max-workers调低，再调小--max-chunk-size；要是是API限额或者余额的问题，改参数可没用。

5. 版式看着不对：带--keep-intermediate重跑，先看XML里抽出来的文本对不对，再换服务商或者改源PPT。

还有个很小但挺闹心的坑：要是PPT里有很多重复的页眉页脚，缓存会帮你省掉重复翻译的钱；但要是同一句话在不同上下文里意思不一样，缓存也可能让结果太统一。商务方案、技术术语多的文件，先拿一两页做样例，确认术语口径没问题再批量跑。

我一般啥时候用它？比如售前同事拿到一份中文产品方案，要快速出英文版给海外客户先看，手动复制每个文本框太慢，在线工具又经常把版式弄散。把这个skill跑通后，先用小样例确认术语和版式没问题，再把正式PPT丢进去批量处理，最后人工扫一遍标题、表格和页脚就行。它省的是重复搬文字、保版式的时间，不是替你做最终审校的。

最后总结下：tristan-mcinnis/PPT-Translator-Formatting-Intact-with-LLMs skill的本地安装其实不复杂，难点在搞清楚边界。Claude类宿主要复制完整的skill目录，Python CLI要在scripts里装依赖，翻译肯定得有对应服务商的API Key。先用help、pytest和一页样例把链路跑通，再处理正式PPT，出错了就按「目录→密钥→参数→XML→API限额」这个顺序查，心态稳很多。