ドキュメント翻訳

このプロジェクトではAWS BedrockのHaiku 3.5モデルを使用して、ドキュメントを英語から複数言語へ自動翻訳します。翻訳システムは効率的で正確、かつ使いやすいように設計されています。

対応言語

現在以下の言語をサポートしています:

日本語 (jp)
フランス語 (fr)
スペイン語 (es)
ドイツ語 (de)
中国語 (zh)
韓国語 (ko)

動作原理

翻訳システムは次のように動作します:

h2見出しでドキュメントを分割 - 効率的な処理と翻訳モデルへの適切なコンテキスト提供を実現
Markdownフォーマットの保持 - すべてのMarkdown構文、コードブロック、HTMLタグは翻訳中に保持されます
Frontmatterの特別処理 - YAML frontmatterは構造を保持したまま翻訳されます
インクリメンタル翻訳 - デフォルトで変更されたファイルのみを翻訳し、時間とリソースを節約

ローカルでの翻訳実行

ドキュメントをローカルで翻訳するにはscripts/translate.tsスクリプトを使用します:

# 変更ファイルのみを日本語に翻訳（デフォルト）
./scripts/translate.ts

# すべてのファイルを翻訳
./scripts/translate.ts --all

# 特定の言語を指定して翻訳
./scripts/translate.ts --languages jp,fr,es

# 実際の翻訳なしで処理内容を表示
./scripts/translate.ts --dry-run

# 詳細な出力を表示
./scripts/translate.ts --verbose

GitHubワークフロー

GitHubワークフローは、プルリクエストで英語ドキュメントファイルに変更が加えられた場合に自動的に翻訳を実行します。ワークフローは以下の処理を行います:

英語ドキュメントファイルへの変更を検出
AWS Bedrockを使用して変更ファイルを翻訳
翻訳結果をソースブランチにコミット
PRに翻訳ステータスを反映

ワークフローの手動トリガー

GitHub Actionsタブから手動で翻訳ワークフローを起動することも可能です。これは以下の場合に便利です:

全ドキュメントの完全翻訳を実行する場合
特定の言語を指定して翻訳する場合
翻訳スクリプトに変更を加えた後の翻訳更新

AWS設定

翻訳システムはAWS BedrockのHaiku 3.5モデルを使用します。この機能を使用するには以下が必要です:

AWS認証情報 - ローカル開発ではAWS CLIまたは環境変数で認証情報を設定
IAMロール - GitHub Actionsでは、OIDC認証とAWS Bedrockに必要な権限を持つIAMロールを設定

必要な権限

IAMロール/ユーザーには以下の権限が必要です:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-3-haiku-20240307-v1:0"
      ]
    }
  ]
}

翻訳品質

翻訳品質は一般的に高い水準ですが、以下の点に注意してください:

技術用語 - 技術用語は英語のまま保持されるように設定されています
コードブロック - コードブロックは元の形式を保持するため翻訳されません
コンテキスト認識 - 翻訳モデルはドキュメントの文脈を理解するため、技術文書の翻訳に適しています

翻訳のカスタマイズ

scripts/translate.tsファイルを修正することで翻訳プロセスをカスタマイズ可能です。主なカスタマイズ例:

追加言語のサポート
翻訳モデルの変更
翻訳用プロンプトの調整
ドキュメント分割・処理方法の変更

トラブルシューティング

翻訳プロセスで問題が発生した場合:

AWS認証情報を確認 - 正しく設定されていることを確認してください
AWSリージョンを確認 - AWS Bedrockが利用可能なリージョンを使用しているか確認
詳細出力モードで実行 - --verboseフラグを使用して詳細ログを確認
レート制限を確認 - 大規模な翻訳ジョブではAWS Bedrockのレート制限が影響する可能性があります