game-translator-mcp

汎用ゲーム中国語化 MCP ツール —— ゲームディレクトリをスキャンし、AI 翻訳を呼び出し、中国語テキストを書き戻します。

位置づけ: AI Agent から呼び出せる「中国語化機能」であり、独立した中国語化ソフトウェアではありません。mc-translator-mcp、mc-pack-builder-mcp などのツールと連携できます。

適用範囲

本ツールは、テキストがプレーンフファイルで保存されているゲーム / Mod の中国語化を対象としており、「テキスト中国語化」であり「リソースパック注入」ではありません。

非対応範囲 / 既知の制限：

• Unity のパッケージ化された .pak / .vpk / catalog.json バイナリリソースは、先に解包が必要です

• 幻兽帕鲁など .locres を使用する Unreal ゲームは UnrealPak による解包が必要です

• War Thunder / PUBG などサーバー配信または暗号化されたテキストのクラックは対応していませません

• 10 MB を超えるテキストファイル（バイナリの誤検出防止）は、スキャン時に自動的にスキップされます

注意：Unity ゲームには多数の .json / .xml がありますが、その多くはゲーム本文ではなくエンジン設定です。スキャナはそのまま返すため、翻訳する価値があるかは利用者の判断となります。

Related MCP server: ttsstt-mcp-server

使用条件

AI ベンダーは利用者がすべて設定できます（設定済みの key を検出して使用。優先順位 custom > agnes > dashscope > deepseek）：

• 自定义 OpenAI 兼容供应商（推奨、最も汎用）：TRANSLATOR_API_KEY + TRANSLATOR_BASE_URL + TRANSLATOR_MODEL で、任意の互換インターフェースを利用可能

• agnes ai：AGNES_API_KEY + AGNES_BASE_URL + AGNES_MODEL

• 通義千問：DASHSCOPE_API_KEY

• DeepSeek（オプションの fallback） DEEPSEEK_API_KEY`

インストール

cd game-translator-mcp
pip install -e ".[dev]"

設定

.env.example を .env にコピーし、使用するベンダーを記入します。

cp .env.example .env

どれかの方式を選択します（検出された key が使われます。優先順位 custom > agnes > dashscope > deepseek）：

# 方式 A（推荐，最通用）：自定义 OpenAI 兼容供应商 —— 填你自己的 key / 网关地址 / 模型名
TRANSLATOR_API_KEY=sk-xxx
TRANSLATOR_BASE_URL=https://your-gateway.example.com/v1
TRANSLATOR_MODEL=your-model

# 方式 B：agnes ai（也可展开为 OpenAi 兼容平台）
# AGNES_API_KEY=sk-xxx
# AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
# AGNES_MODEL=agnes-2.5-flash

# 方式 C：通义千问
# DASHSCOPE_API_KEY=sk-your-qwen-key-here

# 方式 D：DeepSeek（可选，主供应商失败时 fallback）
# DEEPSEEK_API_KEY=

BATCH_SIZE=15                # 每批翻译条数，越高越省 token
OUTPUT_DIR=translated_output # 汉化输出目录

設定優先順位：まず環境変数を読み、次にプロジェクトルートの .env を読み、最後に内蔵デフォルト値。 API Key は利用者がご用意ください。対応プラットフォーム（agnes / 通義 / DeepSeek / その他の OpenAI 互換ゲートウェ）で申請してください。

可移転性：本ツールはどのクラウドベンダーにも依存しません。対象のマシンで上記のいずれのセットを設定するだけでローカル実行でき、CI / Docker / 任意のプラットフォームに対応しています。

起動方式

MCP サーバーとして（AI Agent から呼び出す）

python -m game_translator_mcp

Trae / Claude Desktop の設定例：

{
  "mcpServers": {
    "game-translator-mcp": {
      "command": "python",
      "args": ["-m", "game_translator_mcp"]
    }
  }
}

LangChain Agent 連携（PYTHONPATH を src/ に）：

{
  "mcpServers": {
    "game-translator-mcp": {
      "command": "python",
      "args": ["-m", "game_translator_mcp"],
      "env": {
        "PYTHONPATH": "/path/to/game-translator-mcp/src"
      }
    }
  }
}

CLI モード

# 扫描游戏目录，列出可翻译文件
python -m game_translator_mcp check <游戏目录路径>

# 执行完整汉化
python -m game_translator_mcp translate <游戏目录路径> --modid mygame

# 预览翻译效果（不写入文件）
python -m game_translator_mcp translate <游戏目录路径> --modid mygame --dry-run

# 列出 Steam 库中的可翻译游戏
python -m game_translator_mcp steam

MCP ツール

使用例

自然言語での呼び出し（Trae 経由）

"私のSteamゲームの中から、翻訳可能なテキストがあるものをスキャンして"

"「RimWorld」の英語テキストを翻訳して"

"「Factorio」の中国語化をプレビューして。実際に書き込むな"

直接 CLI から呼び出し

# 汉化一个模组目录
python -m game_translator_mcp translate "path/to/my-mod" --modid mymod

# 输出目录默认为 translated_output/
# 汉化报告自动生成到 translated_output/report.txt

出力構成

translated_output/
├── my-mod/
│   ├── assets/my-mod/lang/zh_cn.json
│   └── ...（保持原目录结构）
├── rimworld/
│   ├── Assets/StreamingAssets/Localization/zh-cn.json
│   └── ...
└── report.txt           # 汉化报告

コアモジュール

設計ポイント

1. スマートキャッシュ：{modid}::key::value の SHA-256 ハッシュにより、同じ原文は一度だけ度し、結果を translator_cache.json に永続化します。

2. 既存翻訳のスキップ：出力ディレクトリに同じ形式の翻訳ファイルが存在する場合は自動的にスキップし、コミュニティ翻訳の上書きを防ぎます。

3. バッチ翻訳：各リクエストに最大 BATCH_SIZE 件のエントリを含め、一度の API 呼び出しで全部の結果を返します。トークンと遅延を大幅に削減します。

4. ベンダー適応：ユーザー設定を検出した key を自動で使用（custom > agnes > dashscope）、オプションで DeepSeek を fallback として利用。特定のベンダーに束縛されません。

5. 非侵襲的な出力：デフォル gor の copy モードで独立した出力ディレクトリを生成し、元のゲーム・ファイルを変更しません。

テスト

python -m pytest tests/ -v
# 或
pytest tests/ -v

すべてのテストは Windows + Python 3.14 環境で失敗しています（77 tests passed、新增 VDF UTF-16 ケースを含む）。

実機での中国語化テスト

実際のゲームファイルを使用した端末から端末までの中国語化検証（agns ai 使用）を行い、結果は tests/report/ にアーカイブしています：

• ✅ REPO（モンスターのマッピング）：Menu/HUD/Game.tsv の合計 603 件をすべて実際に翻訳して TSV に書き戻し、成功 602 件

• ✅ Portal 2：Source エンジン VDF（UTF-16）エンドツーエンド中国語化で、basemodui_english.txt の抽出可能な 2231 件を翻訳し、UTF-16 BOM を保持して書き戻し

• ✅ Biped 2：localization_en.txt のプレーンテキスト key=value 928 件を直接中国語化可能

• 🔍 その他のゲーム（Isaac / Palworld / CSGO など）：テキストはプライムパック内にカプセル化されているか、エンジン設定のみです。詳細はテスト報告を参照してください。

ゲームライブラリの拡充を歓迎します

本ツールは任意のプレーンテキスト形式のゲーム / Mod をサポートしています。あなたのゲームのテキストがプレーンファイル（.json / .tsv / .lang / .sii / .vdf など）として存在する場合、Issue や PR でゲームライブラリを追加し、既存パーサーを一緒に拡張しましょう。詳細な手順は tests/reports/ を参照してください。

既存のツールチェーンとの関係

コントリビュートガイド

新しいゲーム形式への対応：

1. parser.py に新しい解析関数を追加（例：_parse_locres）

2. _PARSERS 辞書に登録

3. scanner.py の SUPPORTED_EXTENSIONS に拡張子を追加

4. tests/test_parser.py に対応するテストを追加

Licenseuses

MIT License — 自由に使用・修正・再配布できます。