gemini-translate

Gemini Translate

Gemini CLI を翻訳サブエージェントとして使用し、コンテンツファイル（Markdown、JSON、YAML フロントマター）を一括翻訳します。Claude がパイプラインを統括し、翻訳漏れを特定し、用語集のコンテキストを含むプロンプトを作成して、単一の CLI 呼び出しで Gemini に処理を依頼し、出力構造を検証してファイルを書き込みます。

Gemini CLI を使う理由

• OAuth 経由で Google AI Ultra プランを利用できます（API キーは不要です）
• 100 万トークンのコンテキストで、用語集全体と多数のソースファイルを一度の呼び出しに収められます
• ファイルごとではなく、起動コストは約 13 秒で一度だけです
• オーケストレーション、検証、ファイル書き込みは Claude が引き続き管理します

前提条件

• Gemini CLI がインストールされ、認証済みであること（gemini が PATH 上にあり、OAuth が設定済みであること）
• ソースコンテンツファイルが一貫した構成であること（フロントマター付き Markdown、JSON など）

パイプラインの概要

Claude: find translation gaps (missing .es.* files, parity tests)
  |
Claude: read source files + glossary + existing translations for tone
  |
Claude: build batch prompt and call gemini-translate.sh
  |
Gemini: translate all files in one shot, return JSON
  |
Claude: parse response, validate structure, write .es.* files
  |
Claude: run project tests (i18n symmetry, coverage)

使い方

ステップ 1：翻訳漏れを特定する

対応するロケールのファイルがないコンテンツファイルを探します。

# Generic pattern -- adjust paths and extensions for your project
for f in content/**/*.md; do
  base=$(basename "$f")
  [[ "$base" == *.es.* ]] && continue
  name="${base%.*}"
  dir=$(dirname "$f")
  [ ! -f "$dir/${name}.es.md" ] && echo "MISSING: $f"
done

または、プロジェクトに i18n の整合性テストがある場合は、それを実行します。

ステップ 2：用語集を準備する

一貫して翻訳する必要がある用語の用語集を作成します。用語集は、プロンプトに埋め込むシンプルなテキストブロックです。

## Glossary (EN -> ES)
- "OB/GYN Physician" -> "Medico OB/GYN"
- "High-risk pregnancy" -> "Embarazo de alto riesgo"
- "Certified Nurse Midwife" -> "Enfermera Partera Certificada"

プロジェクトに既存の用語集（Python の辞書、CSV、JSON）がある場合は、スクリプトを呼び出す前にこの形式に変換してください。スクリプトには --glossary で用語集ファイルを指定できます。

ステップ 3：翻訳を一括実行する

bash gemini-translate.sh \
  --source-lang en \
  --target-lang es \
  --glossary glossary.txt \
  --model gemini-2.5-pro \
  --instructions "Use formal 'usted'. Latin American Spanish, not Spain. Warm but professional tone for patient-facing medical content." \
  file1.md file2.md file3.md

スクリプトの処理内容：

1. すべてのソースファイルを読み込みます
2. 用語集、指示、すべてのファイル内容を含む単一のプロンプトを作成します
3. gemini -p "..." -o json --approval-mode plan を呼び出します
4. JSON 応答を解析し、各翻訳を JSON 配列として標準出力に出力します

ステップ 4：Claude が検証して書き込む

スクリプトの実行後、Claude は次の処理を行います。

1. JSON 出力を解析します
2. 翻訳された各ファイルについて、次の点を確認します。
   • フロントマターのキーがソースと完全に一致していること
   • リンク、画像パス、ブランド名が保持されていること
   • Gemini が `` フラグを出力していないこと（出力していた場合はユーザーに提示します）
3. .es.* ファイルを書き込みます
4. プロジェクトの i18n テストを実行します

スクリプトのリファレンス

gemini-translate.sh

Usage: gemini-translate.sh [OPTIONS] FILE [FILE...]

Options:
  --source-lang LANG    Source language code (default: en)
  --target-lang LANG    Target language code (default: es)
  --glossary FILE       Path to glossary file (term mappings, one per line)
  --instructions TEXT   Additional translation instructions for tone/style
  --model MODEL         Gemini model override (default: system default)
  --max-tokens N        Max estimated input tokens per batch (default: 80000)
  --gemini-bin PATH     Path to gemini binary (bypasses wrapper detection)
  --dry-run             Print the prompt without calling Gemini

Output: JSON array to stdout
  [
    {"file": "about.md", "translation": "---\ntitle: Acerca de\n---\n..."},
    {"file": "careers.md", "translation": "---\ntitle: Carreras\n---\n..."}
  ]

Exit codes:
  0  Success
  1  Gemini CLI not found or not authenticated
  2  No input files provided
  3  Gemini returned an error or unparseable output

翻訳品質ルール

これらのルールは Gemini に送信するプロンプトに埋め込まれています。

1. 構造を完全に保持する：フロントマターのキー、Markdown の書式、リンク、HTML タグ、画像パス
2. 翻訳しない：ブランド名、固有名詞、URL、ファイルパス、認証情報（MD、DO、CNM など）
3. 医療用語：用語集を使用してください。用語が用語集に載っておらず、判断に迷う場合は `` で囲んでください
4. トーン：ソース文書のトーンに合わせてください。患者向けの医療コンテンツでは、温かく、安心感のある、専門的な表現にしてください
5. 出力形式：変更した部分だけでなく、翻訳済みファイルの完全な内容（フロントマターと本文）を返してください

他のプロジェクトへの適用

このスキルはプロジェクトに依存しません。新しいコードベースで使用するには、次の手順に従います。

1. ファイル規則：プロジェクトのロケールファイル命名パターン（.es.md、.es.json、locales/es/ など）を設定します
2. 用語集：ドメイン固有の用語を用語集ファイルにまとめます
3. 指示：対象言語向けのスタイルガイドを 1 段落で作成します
4. 検証：Claude にプロジェクトの i18n テストを実行させるか、キーを比較する簡単なチェックを作成します

Gemini CLI ラッパーとの互換性

多くのユーザーは、デフォルトで --yolo／-y を追加するシェルラッパー（例：~/bin/gemini）を使用しています。これは --approval-mode と競合します。スクリプトは次の方法でこの問題を回避します。

1. pnpx @google/gemini-cli を優先します（パッケージを直接呼び出すため、ラッパーを経由しません）
2. pnpx を利用できない場合に限り、PATH 上の gemini にフォールバックします
3. --gemini-bin /path/to/binary を指定すると、検出方法を完全に上書きできます

スクリプトは構造化出力に -o json を使用し、{session_id, response, stats} 形式のエンベロープを返します。組み込みの Python パーサーは response フィールドを抽出し、Markdown のコードフェンス、ヌルバイト、MCP の警告プレフィックスを自動的に処理します。

トークンベースのバッチ処理

固定のファイル数ではなく、スクリプトは入力トークン数（1 トークン ≒ 4 文字）を推定し、予算に達するとファイルの追加を停止します。デフォルトの --max-tokens 80000 は、翻訳出力に必要な余裕（EN->ES の場合、入力の約 1.2 倍）を残します。予算を超えたファイルはスキップとして一覧表示されるため、呼び出し元は後続のバッチを実行できます。

切り詰めからの復旧

Gemini が出力トークン制限に達し、JSON がエントリーの途中で切り詰められた場合、スクリプトは次の手順で復旧します。

1. 不完全な JSON を検出する
2. 有効な JSON の境界を見つけるため、末尾から段階的に切り詰める
3. 最後の（切り詰められた可能性が高い）エントリーを削除する
4. 復元できた完全な翻訳の数を報告する

エージェント型ワークフローとバイブコーディング

• 反復的な翻訳： 最初のバッチ実行で、完璧な文体や構造の保持が実現するとは限りません。小規模なテストバッチを作成し、文体と書式を確認して、一貫して発生する翻訳エラーを特定します。用語集またはプロンプトの指示を一度に 1 つの変数だけ調整し、プロジェクト全体を処理する前にテストを再実行してください。
• バイブコーディング： 翻訳バッチを実行する前に、作業中のソースコンテンツと用語集の更新をローカルでコミットしてください。また、生成された .es.* ファイルは別途コミットしてください。モデルが構造を幻覚した場合に、簡単に元に戻せます。

制限事項

• 1 回の呼び出しにつき 1 つの言語ペア： スクリプトが扱うのは 1 つの原文・翻訳先のペアです。複数言語のプロジェクトでは、翻訳先の言語ごとに実行してください。
• Gemini CLI の起動： バッチ呼び出しごとに約 13 秒のオーバーヘッドが発生します。バッチ処理によって、この負荷を分散できます。
• 出力トークン制限： デフォルトの予算は入力トークン数 80K です。切り詰めが発生した場合は、--max-tokens の値を下げてください。
• ストリーミング非対応： スクリプトは応答全体を待ちます。大規模なバッチでは、起動時間に加えてモデルの処理に 30～60 秒かかる場合があります。
• Python 3 が必要： JSON の抽出には埋め込みの Python スクリプトを使用します。