game-translator-mcp

A general-purpose game localization MCP tool — scans game directories, calls AI for translation, and writes Chinese text back.

Purpose: a "translation capability" that can be invoked by an AI Agent, not a standalone localization tool. It can work alongside tools such as mc-translator-mcp and mc-pack-builder-mcp.

Scope

This tool is designed for translating games/mods whose text is stored in plain-text files; it performs "text translation" rather than "resource pack injection."

Out of scope / known limitations:

• Unity packaged binary resources such as .pak / .vpk / catalog.json must be unpacked before they can be processed.

• Unreal games like Palworld that use .locres need to be unpacked with UnrealPak.

• War Thunder / PUBG and other server-delivered or encrypted text are not supported (no cracking/decryption support).

• Text files over 10MB are skipped automatically during scanning to avoid accidentally scanning binaries.

Tip: Unity games contain many .json/.xml files, but most are engine configuration rather than in-game copy; the scanner reports them as-is, and you decide whether they are worth translating.

Related MCP server: translator-ai

Requirements

The AI provider is entirely configured by you (the configured key is detected and used; priority custom > agnes > dashscope > deepseek):

• Custom OpenAI-compatible provider (recommended, most general): TRANSLATOR_API_KEY + TRANSLATOR_BASE_URL + TRANSLATOR_MODEL, works with any compatible API platform.

• agnes ai: AGNES_API_KEY + AGNES_BASE_URL + AGNES_MODEL

• Qwen (Tongyi Qianwen): DASHSCOPE_API_KEY

• DeepSeek (optional fallback): DEEPSEEK_API_KEY

Installation

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

Configuration

Copy .env.example to .env and fill in the provider you want to use:

cp .env.example .env

Choose any one method (the configured key is detected and used; the priority is 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 # 汉化输出目录

Configuration precedence: environment variables are read first, then the .env file in the project root, and finally built-in defaults. You provide the API Key yourself and request it from the corresponding platform (e.g. agnes / Qwen / DeepSeek / other OpenAI-compatible gateway).

Portability: This tool is not bound to any cloud service provider. As long as any one of the above API parameter sets is configured on the target machine, it will run locally, and it is suitable for CI, Docker, or any platform.

Startup

As an MCP server (for AI Agents)

python -m game_translator_mcp

Trae / Claude Desktop configuration example:

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

LangChain Agent integration (with PYTHONPATH pointing to src/):

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

CLI mode

# 扫描游戏目录，列出可翻译文件
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 tools

Usage examples

Natural language invocation (through Trae)

"Help me scan which of my Steam games have translatable text."

"Help me translate the English text of the game 'RimWorld'."

"Preview the localization of 'Factorio' without actually writing files."

Direct command-line invocation

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

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

Output structure

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

Core modules

Design highlights

1. Intelligent caching: A SHA-256 hash is computed for Translation Resolved High Key in braces (for readability) and the same text is translated exactly once; results are persisted in translator_cache.json.

2. Skip existing translations: If a file with the same format already exists in the output directory, it is skipped automatically so community translations are not overwritten.

3. Batch translation: Each response carries up to BATCH_SIZE entries, and a single API call returns all results. This greatly reduces token usage and latency.

4. Provider adaptive: Detects which key you have configured and uses it (custom > agnes > dashscope), with optional DeepSeek as a fallback; the tool is not tied to any one provider.

5. Zero-invasive output: The default copy mode writes an independent output directory and never changes the original game files.

Testing

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

All tests pass on Windows with Python 3.14 (77 tests passed, including the new VDF UTF-16 case).

Real translation testing

End-to-end translation verification was also performed against real game files (using agnes ai). The results are archived in tests/reports/:

• ✅ REPO: Menu/HUD/Game.tsv with 603 entries was fully translated and written back to TSV, with 602 successful entries.

• ✅ Portal 2: source-engine VDF (UTF-16) end-to-end localization; 2231 plaintext entries in basemodui_english.txt are translatable, and UTF-16 BOM was preserved on write-back.

• ✅ Biped 2: localization_en.txt with 928 entries in key=value form, can be localized directly.

• Others (Isaac / Palworld / CSGO, etc.): the text is wrapped in private resource packs or configuration only; see the test report.

Welcome contributions to the game library

This tool supports any game that stores text in a plain-text format. If your game or mod uses plain-text files (.json / .tsv / .lang / .sii / .vdf etc.), please contribute to the game library through an Issue or PR extension, and help extend the existing parsers. Full guidelines are in tests/reports/.

Relationship to the existing toolchain

Contribution guide

To add support for a new game text format:

1. Add a new parser function (such as _parse_locres) in parser.py

2. Register it in the _PARSERS dictionary

3. Add the extension to SUPPORTED_EXTENSIONS in scanner.py

4. Add a corresponding test in tests/test_parser.py

License

MIT License — free to use, modify, and distribute.