翻译流程

1. 上传 → 保存到 Supabase Storage
2. 文本提取 → 使用 Python (python-pptx) 提取文本
3. 翻译 → 使用 Claude API (TypeScript) 进行翻译
4. PPTX 生成 → 使用 Python 应用翻译文本
5. 预览生成 → 生成幻灯片图像
6. 下载 → 通过 Signed URL 提供下载

デバッグ手順

Python 处理测试

# 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

翻译 API 测试

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

常见问题

1. 相同文本重复问题

• 症状 : 当相同文本出现在多个位置时，第二个及之后的文本不会被翻译
• 原因 : generate_pptx.py 中的 break 语句
• 对策 : 删除 break，处理所有匹配项

2. 大文件超时

• 症状 : 超过 50 张幻灯片时处理超时
• 对策 : 动态设置 _internal/base-translator.ts 中的 max_tokens

3. 日语字体问题

• 症状 : 日语显示为豆腐块（□）
• 对策 : 在 generate_pptx.py 中设置游ゴシック/メイリオ字体

制限事項

限制值的具体数值请参考 src/constants/limits.ts（单一事实来源）。

AI Assistant Instructions

当此技能被激活时：

1. 问题隔离 : 确定是 TypeScript 处理还是 Python 处理的问题
2. 日志检查 : 检查 @/lib/logger 的调试输出
3. 分步验证 : 按照 文本提取 → 翻译 → PPTX 生成的顺序进行验证
4. 激活 venv : Python 处理时务必执行 source ~/.venvs/ppt-trans/bin/activate

Always:

• Python 处理前激活虚拟环境
• 翻译由 TypeScript（Claude API）处理
• 出错时先检查日志再进行修正

Never:

• 不要在 Python 侧实现翻译处理（已在 TypeScript 中实现）
• 不要在没有 venv 的情况下运行 Python 脚本
• 不要尝试处理超出限制的文件

Weekly Installs

119

Repository

yusuketsunoda/ppt-trans

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

gemini-cli119

codex119

opencode119

cursor118

github-copilot117

amp117

翻訳フロー

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

デバッグ手順

Python処理のテスト

# 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

翻訳APIのテスト

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

よくある問題

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

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

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

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

3. 日本語フォント問題

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

制限事項

制限値の具体的な数値は src/constants/limits.ts を参照（SSOT）。

AI Assistant Instructions

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

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

Always:

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

Never:

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

Weekly Installs

119

Repository

yusuketsunoda/ppt-trans

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

gemini-cli119

codex119

opencode119

cursor118

github-copilot117

amp117