game-translator-mcp

Универсальный MCP-инструмент для локализации игр — сканирует каталог игры, вызывает AI-перевод и записывает китайский текст обратно.

Назначение: это «способность локализации», которую может вызывать AI-агент, а не самостоятельное ПО для перевода. Может работать совместно с mc-translator-mcp, mc-pack-builder-mcp и другими инструментами.

Область применения

Инструмент предназначен для локализации игр/модов, где текст хранится в виде открытых текстовых файлов — это «перевод текста», а не «внедрение ресурс-паков».

Неприменимо / известные ограничения:

• Запакованные бинарные ресурсы Unity — .pak / .vpk / catalog.json, требуют распаковки перед обработкой

• Игры на Unreal с .locres (например, Palworld) требуют распаковки через UnrealPak

• Тексты, отправляемые с сервера или зашифрованные в War Thunder / PUBG и подобных играх, — взлом не поддерживается

• Файлы более 10 МБ (защита от ошибочного сканирования бинарных данных) при сканировании автоматически пропускаются

Подсказка: в играх Unity есть много .json/.xml, но большинство из них — конфигурация движка, а не игровой текст; сканер вернёт их как есть, решать, стоит ли переводить, должен пользователь.

Related MCP server: ttsstt-mcp-server

Требования

AI-провайдер полностью настраивается пользователем (определяется, какой ключ сконфигурирован, приоритет custom > agnes > dashscope > deepseek):

• Пользовательский провайдер OpenAI-совместимый (рекомендуется, самый универсальный): TRANSLATOR_API_KEY + TRANSLATOR_BASE_URL + TRANSLATOR_MODEL — подходит для любой совместимой платформы

• Agnes AI: AGNES_API_KEY + AGNES_BASE_URL + AGNES_MODEL

• Tongyi Qianwen: DASHSCOPE_API_KEY

• DeepSeek (опциональный запасной): DEEPSEEK_API_KEY

Установка

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

Конфигурация

Скопируйте .env.example в .env и заполните используемого провайдера:

cp .env.example .env

Выберите любой вариант (используется тот ключ, который найден; приоритет 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 / Tongyi / DeepSeek / другой OpenAI-совместный шлюз).

Переносимость: инструмент не привязан ни к какому облачному провайдеру. Достаточно настроить любой из указанных наборов API-параметров на целевой машине для локального запуска — подходит для CI, Docker или любой платформы.

Способы запуска

Как MCP-сервер (для вызова через AI-агента)

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 возвращает все результаты, что сильно снижает расход токенов и задержку

4. Адаптивность провайдера: определяется, какой ключ настроен у пользователя (custom > agnes > dashscope), optional DeepSeek как fallback; привязки к одному провайдеру нет

5. Нулевое вмешательство: по умолчанию режим copy создаёт отдельный выходной каталог, не изменяя исходные файлы игры (game files)

Тестирование

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/Gаме.tsv — 603 записи, все реально переведены и записаны обратно в TSV, успешно — 602

• ✅ Port ал 2: Source VDF (UTF-16) енд-то-енд локализация, в basemodui_english.txт — 2231 открытых пеерводимых запией, в записи сохранен UTF-16 BOM

• ✅ B ipe д 2: localization_п.тxt — открытое 928 запией key=value, может бытиь молеку переведено

• 🔍 Остальные игры (Исааc / Palворлд / CSGО и драг.): тексст мп. в закрытую ресурсных пакетах или только конфигурция двигка, подробн в тест-отчете

Добро пожалова в пополнение библиотеки игр

Инструмент поддерживает любые игры/моды в открытых текстовых форматах. Если текст вашей игры находится в открытых текстовых файлах (.json / .tsv / .lang / .sii / .vdf и т.п.), добро пожаловать дополняей библиотеку через Issue / PR, вместе расширим существующие парсеры. Подробное руководствооо в tests/reports/.

Отношние с сущесвующей цепочкой инструментов

Руководство по вкладу

Поддерзка нового игрового формата:

1. В parsers.py добавьте новую функцу парсинга (напр., _par se_locres)

2. Зарегистрируйте в словаре _پرSERЗРS

3. В scade.py добавьте расширение в SUPPORTED_EXTEFORЗ

4. Добравьте соответвующий тест в tessts/test_parte.py

Лицензия

MIT License — свобоодное испольование, изменне и распростран.