game-translator-mcp

通用游戏汉化 MCP 工具 —— 扫描游戏目录，调用 AI 翻译，回写中文文本。

定位：一个可以被 AI Agent 调用的「汉化能力」，而非独立的汉化软件。可与 mc-translator-mcp、mc-pack-builder-mcp 等工具协同工作。

适用范围

本工具面向文本以明文文件存储的游戏/模组进行汉化，属于"文本汉化"而非"资源包注入"。

不适用范围 / 已知限制：

• Unity 打包的 .pak / .vpk / catalog.json 二进制资源，需先解包才能处理

• 幻兽帕鲁等使用 .locres 的 Unreal 游戏，需 UnrealPak 解包

• 战雷 / 绝地求生等服务端下发或加密的文本，不提供破解支持

• 超过 10MB 的文本文件（防误扫二进制），扫描时自动跳过

提示：Unity 游戏虽有大量 .json/.xml，但多数是引擎配置而非游戏文案；扫描器会如实返回，是否值得翻译由使用者判断。

Related MCP server: translator-ai

使用条件

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 兼容网关）。

可移植性：本工具不绑定任何云服务供应商，只要在目标机器配置好上述任一套 API 参数即可本地运行，适用于 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' 的汉化效果，不要实际写入"

直接命令行调用

# 汉化一个模组目录
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 调用返回全部结果，大幅降低 token 和延迟

4. 供应商自适应：检测用户配置了哪个 key 就用哪个（custom > agnes > dashscope），可选 DeepSeek 做 fallback，不绑定任何一家

5. 零侵入输出：默认 copy 模式生成独立输出目录，不修改原游戏文件

测试

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

所有测试均在 Windows + Python 3.14 环境下通过（77 tests passed，含新增 VDF UTF-16 用例）。

真实汉化测试

结合真实游戏文件做了端到端汉化验证（使用 agnes ai），结果已归档到 tests/reports/：

• ✅ 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 等）：文本封装于私有资源包或仅引擎配置，详见测试报告

欢迎补充游戏库

本工具支持任意明文文本格式的游戏/模组。如果你的游戏文案以明文文件（.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 中添加对应测试

许可证

MIT License — 自由使用、修改和分发。