适用范围	说明
支持的文本格式	`.json` / `.lang` / `.txt` / `.ini` / `.xml` / `.yaml` / `.sii` / `.tsv` / `.vdf`（UTF-8 / UTF-16 自动 BOM 检测）/ `.csv` / `.properties` / `.po` / `.strings` / `.resx` / `.xliff` / `.rpy` / `.srt` / `.ass`
典型的适用对象	Minecraft 模组、欧洲卡车模拟器 2、Source 引擎游戏（Portal 2 / HL2 / L4D 的 VDF）、Ren'Py 视觉小说（galgame）、字幕（SRT/ASS）、gettext(.po)、Unity 明文本地化表、Steam 明文配置文件
输入	游戏根目录或任意文本文件目录
输出	独立汉化目录（copy 模式），不改动原游戏文件

📚 想知道你的游戏在被支持范围内吗？ 先看这里 → 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，但多数是引擎配置而非游戏文案；扫描器会如实返回，是否值得翻译由使用者判断。

使用条件

条件	说明
Python	≥ 3.10
依赖	见 `pyproject.toml`（mcp、openai、pydantic 等）
联网	必须能联网调用 AI 翻译 API
API Key	不绑定任何特定供应商。由使用者自任选一个 OpenAI 兼容供应商，提供 key / base_url / 模型名（见下方「配置」），这是翻译能力的必要前提
可移植性	纯 Python + 标准依赖，可在 Windows / macOS / Linux 本地跑通，无平台耦合
授权	汉化后的文本仅限个人学习 / 非商业用途；商用需确认游戏与模组的二次分发条款

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 工具

工具名	功能
`preview_translate_game`	零成本预览（--dry-run）：先扫出会处理哪些文件、每种格式数量、总条目数、预估 token，不调 AI、不消耗额度、不写文件
`scan_game_directory`	扫描目录，返回可翻译文件列表 + 文本量估算
`translate_game`	完整汉化流程：扫描 → AI 翻译 → 回写 → 生成报告
`dry_run_translate`	抽样预览翻译效果（会调用 AI 翻译一小部分样例），不实际写入文件
`list_steam_games`	发现本地 Steam 库中已安装的可翻译游戏

使用示例

自然语言调用（通过 Trae）

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

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

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

直接命令行调用

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

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

新手怎么用（一句话版）

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

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

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

游戏类型	汉化文件该放哪	说明
我的世界模组/资源包	装成一个资源包（把 `translated_output` 里的 `.json` 按 `assets/<modid>/lang/` 结构打包，或用 mc-pack-builder-mcp 生成），在游戏里启用该资源包	模组文案以官方资源包方式覆盖
Steam / 大多单机游戏	找到游戏目录里的原语言文件（英文的 `en_us.json` / `Localization` 文件夹），把汉化文件改名成游戏读取的那个语言名（比如 `zh_cn.json`），覆盖进去	改完重进游戏/重启生效
只有特定语言名的	作为可选语言丢进游戏的本地化目录	在游戏设置里切换语言到中文

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

# 以某游戏的 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           # 汉化报告

核心模块

模块	功能
`scanner.py`	扫描游戏目录，识别可翻译文件，过滤二进制/大文件
`parser.py`	多格式文本解析器（JSON / LANG / TXT / INI / XML / YAML / SII / TSV / VDF / CSV / properties / PO / strings / resx / xliff / rpy / srt / ass）
`translator.py`	任意 OpenAI 兼容供应商批量翻译（custom / agnes / 通义 / DeepSeek）+ SHA-256 缓存
`writer.py`	回写翻译结果，保持原格式，支持 copy / inplace 两种模式
`reporter.py`	生成清晰的汉化报告（成功 / 跳过 / 失败统计）
`steam.py`	Steam 游戏发现，解析 VDF 索引文件
`mcp_server.py`	MCP 服务器入口，暴露 5 个工具供 AI Agent 调用
`cli.py`	命令行接口，支持 check / preview / dry-run / translate / steam 子命令

设计要点

智能缓存：对 {modid}::key::value 做 SHA-256 哈希，相同原文只翻译一次，结果持久化到 translator_cache.json
零成本预览：preview_translate_game 先扫文件、估条目数和 token，不调 AI、不写文件，帮你决定要不要花钱翻译
已有汉化跳过：若输出目录中已存在相同格式的翻译文件，自动跳过，避免覆盖社区翻译
批量翻译：每条请求携带最多 BATCH_SIZE 个条目，一次 API 调用返回全部结果，大幅降低 token 和延迟
供应商自适应：检测用户配置了哪个 key 就用哪个（custom > agnes > dashscope），可选 DeepSeek 做 fallback，不绑定任何一家
零侵入输出：默认 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/
新格式接入步骤见下方「贡献指南」

与现有工具链的关系

工具	协作方式
`mc-translator-mcp`	Minecraft 专用强化版；本工具的 MC 子集
`mc-pack-builder-mcp`	构建整合包时自动检测模组是否需要汉化，并调用本工具完成翻译
`mc-mod-config-mcp`	汉化完成后检查配置文件格式是否正常
LangChain Agent	通过 MCP stdio 协议接入，支持自然语言驱动汉化流程

贡献指南

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

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

许可证

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

FAQs

What is game-translator-mcp?

Is game-translator-mcp well maintained?

game-translator-mcp