mcp-name: io.github.dcd887/game-translator

game-translator-mcp

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

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

适用范围

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

📚 想知道你的游戏在被支持范围内吗？ 先看这里 → SUPPORTED_GAMES.md（含已实测游戏、引擎→格式速查表、不支持清单）。 快速判断口诀：文案只要是明文文件就能汉化；不确定就 python -m game_translator_mcp preview <目录> 零成本看一眼。

不适用范围 / 已知限制：

• Unity 打包的 .pak / .vpk / catalog.json 二进制资源，需先解包才能处理
• 幻兽帕鲁等使用 .locres 的 Unreal 游戏，需 UnrealPak 解包
• 战雷 / 绝地求生等服务端下发或加密的文本，不提供破解支持
• 单个文本文件超过大小阈值（默认 10MB，防误扫二进制），扫描时跳过 —— 阈值可用 --max-size-mb N 或环境变量 SCAN_MAX_SIZE_MB 调高（部分游戏明文配置刚好超 10MB 时很有用）

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

使用条件

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 # 汉化输出目录
SCAN_MAX_SIZE_MB=10          # 单个文本文件大小阈值（MB），超过跳过；明文文件较大的游戏可调高

配置优先级：先读环境变量，其次读项目根目录 .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 模式

# 零成本预览：先看会扫到哪些文件、多少条文本、预估多少 token（不调用 AI、不写文件）
python -m game_translator_mcp preview <游戏目录路径>

# 若游戏的明文配置文件超过 10MB 被跳过，可用 --max-size-mb 调高阈值再扫
python -m game_translator_mcp preview <游戏目录路径> --max-size-mb 30

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

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

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

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

💡 先 preview 再 translate：翻译会消耗 token，默认输出到独立目录 translated_output/ 不会覆盖原文件。正式执行前先跑 preview 估一下工作量，避免白花 token。

MCP 工具

使用示例

自然语言调用（通过 Trae）

"帮我扫描一下我的 Steam 游戏里哪些有可翻译文本"

"帮我翻译 'RimWorld' 这个游戏的英文文本"

"预览一下 'Factorio' 的汉化效果，不要实际写入"

直接命令行调用

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

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

新手怎么用（一句话版）

1. 先预览，不花钱：python -m game_translator_mcp preview "游戏目录" → 看会翻译多少条。
2. 觉得量合适就翻译：python -m game_translator_mcp translate "游戏目录" --modid mygame → 结果输出到 translated_output/，原文件一个都不动。
3. 翻好了？照着下面「导入汉化」复制回游戏里，中文就生效了。

怎么把汉化「装」进游戏（导入 / 覆盖原文件教学）

本工具默认是copy 模式：只把翻译结果写到 translated_output/ 目录，绝不侵入你的原游戏文件。这样安全，但中文不会立即生效——你需要自己把汉化文件放进游戏认得到的位置。不同游戏的「位置」不一样，通常是这三种情况：

⚠️ 覆盖前请一定留备份——这是能安全撤回去的唯一办法：

# 以某游戏的 Localization/english.json 为例：先把原文件备份，再覆盖
cp "游戏目录/Localization/english.json" "游戏目录/Localization/english.json.bak"
cp "translated_output/你汉化后的文件.json" "游戏目录/Localization/english.json"

如果你不确定该放哪，直接把游戏目录 + 汉化输出目录一起发给 AI，让它帮你判断文件对应关系、给出准确的复制命令 —— 因为本工具就是给 AI Agent 调用的。

需要我把这份「导入/覆盖」说明做成逐步演示（配上具体游戏的实际路径）吗？告诉我你的游戏和目录，我就演示给你看。

输出结构

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. 零成本预览：preview_translate_game 先扫文件、估条目数和 token，不调 AI、不写文件，帮你决定要不要花钱翻译
3. 已有汉化跳过：若输出目录中已存在相同格式的翻译文件，自动跳过，避免覆盖社区翻译
4. 批量翻译：每条请求携带最多 BATCH_SIZE 个条目，一次 API 调用返回全部结果，大幅降低 token 和延迟
5. 供应商自适应：检测用户配置了哪个 key 就用哪个（custom > agnes > dashscope），可选 DeepSeek 做 fallback，不绑定任何一家
6. 零侵入输出：默认 copy 模式生成独立输出目录，不修改原游戏文件

测试

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

所有测试均在 Windows + Python 3.14 环境下通过（89 tests passed，含新增 8 类明文格式用例与零成本预览 preview 用例）。

真实汉化测试

结合真实游戏文件做了端到端汉化验证（使用 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 条，可直接汉化
• ✅ 新增明文格式：.csv / .properties / .po / .strings / .resx / .xliff / .rpy / .srt / .ass 全部做了真实翻译与回写验证；其中 .rpy/.srt/.ass 采用原位 token 回填，不破坏脚本/字幕结构
• 🔍 其余游戏（Isaac / Palworld / CSGO 等）：文本封装于私有资源包或仅引擎配置，详见测试报告

欢迎补充游戏库

本工具支持任意明文文本格式的游戏/模组。如果你的游戏文案以明文文件（.json / .tsv / .lang / .sii / .vdf 等）存储，欢迎通过 Issue / PR 补充游戏库，一起扩展现有解析器。

• 已完成的支持范围见 SUPPORTED_GAMES.md
• 详细测试与新增游戏接入指引见 tests/reports/
• 新格式接入步骤见下方「贡献指南」

与现有工具链的关系

贡献指南

添加对新游戏格式的支持：

1. 在 parser.py 中添加新的解析函数（如 _parse_locres）
2. 注册到 _PARSERS 字典
3. 在 scanner.py 的 SUPPORTED_EXTENSIONS 中添加扩展名
4. 在 tests/test_parser.py 中添加对应测试

许可证

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