SuperClaude/docs/Development/translation-workflow.md

README Auto-Translation Workflow

概要

SuperClaudeは GPT-Translate を使用して、READMEの自動翻訳を実現しています。

🎯 仕組み

graph LR
    A[README.md更新] --> B[GitHub Actions起動]
    B --> C[GPT-4で翻訳]
    C --> D[README-zh.md]
    C --> E[README-ja.md]
    D --> F[自動コミット]
    E --> F
    F --> G[PR作成 or Push]

🔧 セットアップ

1. OpenAI APIキーの設定

GitHub リポジトリの Settings → Secrets → Actions で以下を追加:

Name: OPENAI_API_KEY
Value: sk-proj-xxxxxxxxxxxxx

2. ワークフローの動作

自動起動トリガー:

• README.md が更新されたとき (master/mainブランチ)
• Pull Requestで README.md が変更されたとき
• 手動実行 (workflow_dispatch)

動作:

1. README.md を GPT-4 で翻訳
2. README-zh.md (簡体字中国語) を生成
3. README-ja.md (日本語) を生成
4. 変更があれば自動コミット
5. masterブランチなら直接Push、PRなら新規PR作成

📊 コスト見積もり

ファイルサイズ	GPT-4 Token数	推定コスト
5KB README	~3,000 tokens	~$0.03
10KB README	~6,000 tokens	~$0.06
20KB README	~12,000 tokens	~$0.12

月間コスト見積もり:

• README更新頻度: 月10回
• 1回あたり: $0.06 (2言語翻訳)
• 月額: 約$0.60 (¥90)

🛡️ セキュリティ

APIキー保護:

• GitHub Secrets で暗号化保存
• ワークフローログには表示されない
• Pull Requestからはforkでアクセス不可

権限管理:

permissions:
  contents: write      # 翻訳ファイルのコミット用
  pull-requests: write # PR作成用

🔄 使用方法

自動翻訳 (推奨)

README.mdを更新してコミット・プッシュするだけ:

# README.md を編集
vim README.md

# コミット
git add README.md
git commit -m "docs: update README"
git push origin main

# → GitHub Actionsが自動的に翻訳を実行

手動実行

GitHub UI から:

1. Actions タブを開く
2. "Auto-translate README" を選択
3. "Run workflow" をクリック

ローカルテスト

翻訳品質を事前確認する場合:

# GPT-Translateをローカルで実行
npm install -g gpt-translate
export OPENAI_API_KEY="sk-proj-xxxxx"

gpt-translate --input README.md --output README-zh.md --lang "Simplified Chinese"
gpt-translate --input README.md --output README-ja.md --lang "Japanese"

📝 翻訳品質チェック

自動翻訳後の確認ポイント:

1. 技術用語の正確性

   • フレームワーク名、コマンド名が正しいか
   • コードブロックが保持されているか

2. マークダウン構造

   • 見出しレベルが一致しているか
   • リンクが正しく変換されているか

3. ニュアンス

   • 文脈に合った翻訳か
   • 自然な表現か

修正が必要な場合:

• 自動翻訳後に手動で微調整
• 次回の翻訳時にその修正が維持されるよう考慮

🚫 トラブルシューティング

エラー: "OPENAI_API_KEY not found"

原因: GitHub Secretsが設定されていない

解決策:

# リポジトリ設定を確認
Settings → Secrets and variables → Actions → New repository secret

エラー: "Translation failed"

原因: OpenAI API レート制限

解決策:

• 数分待ってから再実行
• API使用量を確認: https://platform.openai.com/usage

翻訳品質が低い

原因: プロンプトが最適化されていない

改善策:

# .github/workflows/translation-sync.yml
with:
  apikey: ${{ secrets.OPENAI_API_KEY }}
  inputFiles: 'README.md'
  outputFiles: 'README-zh.md'
  targetLanguage: 'Simplified Chinese'
  prompt: 'Translate this technical documentation accurately, preserving all code blocks and technical terms.'

🔗 関連リンク

• GPT-Translate GitHub
• OpenAI API Documentation
• GitHub Actions Documentation

📊 翻訳統計

現在の翻訳実績は GitHub Actions の Workflows タブから確認できます:

Repository → Actions → Auto-translate README → 実行履歴

確認できる情報:

• 翻訳実行回数
• 成功/失敗率
• 実行時間
• 翻訳されたファイルサイズ