game-translator-mcp

범용 게임 중국어 현지화 MCP 도구 — 게임 디렉터리를 스내고, AI 번역을 호출하여 중국어 텍스트를 다시 씁니다.

위장: 파벌된 AI 현지화 소프트웨어가 아니라, AI Agent가 이용할 수 있는 '중국어 현지화'를 제공합니다. 능력입니다. mc-translator-mcp, mc-pck-builder-mcp 등 도구와 함께 사용할 수 있습니다.

适用范围

本工具是针对文本以明文文件形式保存的 game / mod 进行汉化，属于"文本汉化"而不是"资源包嵌入"。

不适用的范围 / 已知限制：

• Unity 打包的 .pak / .vpk / catalog.json 二进制 리소는 먼저解包해야 처리할 수 있습니다

• 팔월드(Palworld) 등 .locres를 사용하는 Unreal 게임은 UnrealPak으로 해수해야 합니다

• War Thunder, PUBG 등 서버에서 내려온或加密한 텍스트는 크래킹을 지원하지 않습니다

• 10MB를 초과하는 텍스트 파일 (이진 파일 오억 방지)은 스캔 시 자동으로 건너뜁니다

참고: Unity 게임에는 .json/.xml가 많지만, 대부분은 엔진 데이터일 뿐이며 게임을 위한 글이 아닙니다. 스나이퍼는 그대로 반환하며, 번역할 만한 가치가 있는지는 사용자가 판단하세요.

Related MCP server: ttsstt-mcp-server

使用前条件 | 说明 |

|---|---| | Python | ≥ 3.10 | | Dependencies | pyproject.toml 참조 (mcp, openai, pydantic 등) | | 互联网 | AI 번역 API 호출을 위해 인터넷 ignore 라이오너스를 확인 | | API Key | 특정 제공업체에 상관하지 않고 사용자自在, 사용자가 linked to an OpenAI -ri 호환 공급/플랫폼 시설되고 key / base_url / model を 통해 제공해야 합니다 (아래 '配置' 참조). This is a necessary condition for translation capability. | | 포터전성 | style 純 Python + 표준 디펀더시, Windows / macOS / Linux에서 전부 local to run, no platform 结합 | | License | 汉ed-text은 개인 학습 / 비록상 업용으로만 사용. 상용은 game / 모드의 올배포 규정을 확인되세요 |

AI 공급사는 전적으로 사용자가 구성합니다 (哪个 key 更 config 才用哪个, priority custom > agnes > dashscope > deepseek):

• Custom定义一个 OpenAI 兼容供应商(推荐, 最通用): TRANSLATOR_API_KEY + TRANSLATOR_BASE_URL + TRANSLATOR_MODEL, any compatibility what

• agnes ai: AGNES_API_KEY + AGNES_BASE_URL + AGNES_MODEL

• 通义千问: DASHSCOPE_API_KEY

• DeepSeek (optional 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 兼容网关).

可移植性: 本工具不与任何云供应商 bind, 只要在 target machine 配置上面的任合任意一套 API 参数即可 local 运,可应用于 CI / Docker 或任合平台.

开始方式

MCP server (供 AI Agent 调用)

python -m game_translator_mcp

Trae / Claude Desktop 配置示例:

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

LangChain Agent integration (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)

"해냐?데이? "▼" "내 스탐 게임에서 번역될 수 있는 텍스트가 있어는 스을 줄"

"'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 with SHA-256 hash, 相同 현재 text once translated, result is in translator_cache.json

2. 已有汉化跳ぶ: 如果输出目录中已有相同认识的文件时, skip it to avoid overwriting community translations.

3. 批量翻译: Each request contains a maximum number of entries BATCH_SIZE, a single API call returns all result, significantly reducing tokens and latency.

4. 闫应商自適応: 检测用户当前配置哪个 key 就自动使用 (custom > agnes > dashscope), optional DeepSeek as fallback, not fixed to any one.

5. 零侵犯输出: Default copy mode produces independent 本地化目录, 不修改原始游戏 files.

测试

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

所有测试均已在 Windows + prompt pipeline 3.14 (77 tests passed，含 ambiguous VDF UTF-16 구성) 以 환지. Steering test.

真实汉化测试

结合真实游戏文件也做了 Kann TODO 到 TODO 的汉化 검증 (using ages ai), 结果已有保存到 tests/reports/:

• ✅ REPO (怪 상地图): Menu/HUD/Game.tsv total 603 cases, all real translation and write back as TSV, success 602 cases.

• ✅ Portal 2 : Source engine VDF (UTF-16) 朝向 end to end translation, basemodui_english.txt all 2231 plain text translatable, write back preserves UTF-16 BOM.

• ✅ Biped 2 : localization_en.txt plaintext key=value 928 cases, can be translated directly.

• 🔍 Other games (Issac / Palworld / CSGO etc.): texts are packed inside private resource archive or engine 配置, read detail in test report.

欢迎重拉引导游

本 tool supports any 明文形式 data format. If your game texts are plain text files (e.g. .json, .tsv, .lang, .ii, .vdf), follow the detailed guide in tests/reports/, extend the parser, welcome to issue/PR.

与 existing tool chain relationship