pptx-translation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PPTX Translation Skill

PPTX翻译技能

PowerPoint翻訳機能の実装・デバッグ・改善のためのスキル。

用于PowerPoint翻译功能实现、调试与优化的技能。

When to Use This Skill

适用场景

PPTX翻訳機能を新規実装・改善する時
翻訳処理でエラーが発生した時
テキスト抽出が正しく動作しない時
翻訳後のPPTXが正しく生成されない時
Python処理（python-pptx）のデバッグ時
Claude API連携の問題を調査する時

新开发或优化PPTX翻译功能时
翻译处理出现报错时
文本提取无法正常工作时
翻译后的PPTX无法正确生成时
调试Python处理（python-pptx）时
排查Claude API集成问题时

アーキテクチャ

架构

┌─────────────────────────────────────────────────────────────┐
│ TypeScript (Next.js Server Actions)                         │
│   └─ src/app/actions/pptx/*.ts                              │
│       ├─ extractTextFromPPTXAction  → Python subprocess     │
│       ├─ translateFileAction        → Anthropic SDK (TS)    │
│       └─ applyTranslationsAction    → Python subprocess     │
└─────────────────────────────────────────────────────────────┘

重要: 翻訳処理はTypeScript + Anthropic SDK（

src/lib/translation/

）

┌─────────────────────────────────────────────────────────────┐
│ TypeScript (Next.js Server Actions)                         │
│   └─ src/app/actions/pptx/*.ts                              │
│       ├─ extractTextFromPPTXAction  → Python subprocess     │
│       ├─ translateFileAction        → Anthropic SDK (TS)    │
│       └─ applyTranslationsAction    → Python subprocess     │
└─────────────────────────────────────────────────────────────┘

重要提示: 翻译处理采用TypeScript + Anthropic SDK（

src/lib/translation/

）

主要ファイル

核心文件

役割	ファイル
オーケストレーション	`src/app/actions/pptx/index.ts`
Python実行	`src/app/actions/pptx/python-execution.ts`
翻訳サービス	`src/lib/translation/translation-service.ts`
ベース翻訳クラス	`src/lib/translation/_internal/base-translator.ts`
PPTX生成	`python_backend/generate_pptx.py`

功能	文件
流程编排	`src/app/actions/pptx/index.ts`
Python执行管理	`src/app/actions/pptx/python-execution.ts`
翻译服务	`src/lib/translation/translation-service.ts`
基础翻译类	`src/lib/translation/_internal/base-translator.ts`
PPTX生成	`python_backend/generate_pptx.py`

翻訳フロー

翻译流程

アップロード → Supabase Storageに保存
テキスト抽出 → Python (python-pptx) でテキスト抽出
翻訳 → Claude API (TypeScript) で翻訳
PPTX生成 → Python で翻訳テキストを適用
プレビュー生成 → スライド画像を生成
ダウンロード → Signed URLで配信

上传 → 保存至Supabase Storage
文本提取 → 使用Python（python-pptx）提取文本
翻译 → 通过Claude API（TypeScript）完成翻译
PPTX生成 → 使用Python应用翻译后的文本
预览生成 → 生成幻灯片图片
下载 → 通过Signed URL分发

デバッグ手順

调试步骤

Python処理のテスト

Python处理测试

bash

undefined

bash

undefined

venvパスはCLAUDE.local.md参照

venv路径请参考CLAUDE.local.md

source ~/.venvs/ppt-trans/bin/activate python python_backend/generate_pptx.py
--input original.pptx
--translations translations.json
--output translated.pptx

undefined

source ~/.venvs/ppt-trans/bin/activate python python_backend/generate_pptx.py
--input original.pptx
--translations translations.json
--output translated.pptx

undefined

翻訳APIのテスト

翻译API测试

typescript

// src/lib/translation/translation-service.ts をデバッグ
import { logger } from "@/lib/logger";
logger.debug("Translation request", { text, sourceLang, targetLang });

typescript

// 调试 src/lib/translation/translation-service.ts
import { logger } from "@/lib/logger";
logger.debug("Translation request", { text, sourceLang, targetLang });

よくある問題

常见问题

1. 同一テキスト重複問題

1. 重复文本翻译问题

症状: 同じテキストが複数箇所にあると2つ目以降が翻訳されない
原因:
```
generate_pptx.py
```
のbreakステートメント
対策: breakを削除し、全マッチを処理

症状: 同一文本出现多次时，第二次及以后的文本未被翻译
原因:
```
generate_pptx.py
```
中的break语句
解决方法: 删除break语句，处理所有匹配项

2. 大ファイルタイムアウト

2. 大文件超时问题

症状: 50枚超のスライドで処理がタイムアウト
対策:
```
_internal/base-translator.ts
```
のmax_tokensを動的設定

症状: 幻灯片超过50张时处理超时
解决方法: 动态设置
```
_internal/base-translator.ts
```
中的max_tokens参数

3. 日本語フォント問題

3. 日语字体问题

症状: 日本語がトーフ（□）で表示
対策:
```
generate_pptx.py
```
で游ゴシック/メイリオを設定

症状: 日语显示为方块（□）
解决方法: 在
```
generate_pptx.py
```
中设置游ゴシック/微软雅黑字体

制限事項

限制事项

制限値の具体的な数値は

src/constants/limits.ts

を参照（SSOT）。

項目	SSOT
最大スライド数	`src/constants/limits.ts`
最大ファイルサイズ	`src/constants/limits.ts`
対応形式	.pptx のみ（.ppt非対応）
同時翻訳	`src/constants/limits.ts`

具体限制值请参考

src/constants/limits.ts

（单一可信来源SSOT）。

项目	单一可信来源（SSOT）
最大幻灯片数量	`src/constants/limits.ts`
最大文件大小	`src/constants/limits.ts`
支持格式	仅.pptx（不支持.ppt）
同时翻译数量	`src/constants/limits.ts`

AI Assistant Instructions

AI助手使用说明

このスキルが有効化された時:

問題の切り分け: TypeScript処理かPython処理かを特定
ログ確認:
```
@/lib/logger
```
のデバッグ出力を確認
段階的検証: テキスト抽出 → 翻訳 → PPTX生成の順で検証
venv有効化: Python処理時は必ず
```
source ~/.venvs/ppt-trans/bin/activate
```

Always:

Python処理前に仮想環境を有効化する
翻訳はTypeScript（Claude API）で処理する
エラー時はログを確認してから修正する

Never:

Python側で翻訳処理を実装しない（TypeScriptで実装済み）
venvなしでPythonスクリプトを実行しない
制限事項を超えるファイルを処理しようとしない

当启用本技能时:

问题定位: 确定问题出在TypeScript处理还是Python处理环节
查看日志: 检查
```
@/lib/logger
```
的调试输出
分步验证: 按照文本提取 → 翻译 → PPTX生成的顺序进行验证
激活虚拟环境: 处理Python任务时必须执行
```
source ~/.venvs/ppt-trans/bin/activate
```

始终遵循：

处理Python任务前激活虚拟环境
翻译处理必须通过TypeScript（Claude API）完成
出现错误时先查看日志再进行修复

禁止操作：

不要在Python侧实现翻译处理（TypeScript侧已完成）
不要在未激活venv的情况下执行Python脚本
不要尝试处理超出限制范围的文件