# mc-translator-mcp
Minecraft 模组中文翻译 MCP 工具

自动从模组 jar 包提取语言文件，调用通义千问批量翻译，生成中文资源包。

## 安装

```bash
cd mc-translator-mcp
pip install -e .
```

## 配置

**不绑定任何特定 AI 供应商**。复制 `.env.example` 为 `.env`，填任一家的 key 即可（优先级 `custom > agnes > dashscope`，可选 DeepSeek 兜底）：

```bash
cp .env.example .env
```

任选一种方式（检测到哪个 key 就用哪个）：

```bash
# 方式 A（推荐，最通用）：任意 OpenAI 兼容供应商 —— 自已填 key / 网关 / 模型名
TRANSLATOR_API_KEY=sk-xxx
TRANSLATOR_BASE_URL=https://your-gateway.example.com/v1
TRANSLATOR_MODEL=your-model

# 方式 B：agnes ai
# AGNES_API_KEY=sk-xxx
# AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
# AGNES_MODEL=agnes-2.5-flash

# 方式 C：通义千问（阿里云百炼）—— https://bailian.console.aliyun.com/
# DASHSCOPE_API_KEY=sk-xxx
# QWEN_MODEL=qwen-plus

# 方式 D：DeepSeek（可选，主供应商失败时 fallback）
# DEEPSEEK_API_KEY=
# DEEPSEEK_MODEL=deepseek-chat
```

> 所有配置都从环境变量 / `.env` 读取，**任何环境本地都能跑通、可移植**。填好任一家的 key 即可开始翻译；改成别的供应商只需改 `.env`，不用动代码。

### 如何验证配置是否生效

1. **先确认程序能跑**（不联网）：
   ```bash
   python -m mc_translator_mcp --help
   ```
   能看到命令帮助说明安装正常。若报 `No module named mc_translator_mcp`，说明没装好或没在项目目录下运行。

2. **再确认 API Key 被正确加载**：
   ```bash
   python -m mc_translator_mcp dry-run "C:/path/to/某个模组.jar"
   ```
   - 返回**译文样例** → 配置已生效，可以正式翻译；
   - 提示**「未配置可用的 API Key」** → `.env` 没生效或 key 填错，回查 `.env` 文件名（不要叫 `.env.example`）与变量名；
   - 报**网络/鉴权错误** → key/base_url/模型名任一可能不对，对照所选供应商的文档核对。

   > `dry-run` 会抽样翻译少量条目（默认 20 条），消耗极少 token，是验证配置最直接的方式。

## 启动方式

### 作为 MCP 服务器（推荐）
```bash
python -m mc_translator_mcp
```

在 Trae/Claude Desktop 中配置 MCP server：
```json
{
  "mcpServers": {
    "mc-translator-mcp": {
      "command": "python",
      "args": ["-m", "mc_translator_mcp"]
    }
  }
}
```

### CLI 模式
```bash
# 检查 jar 语言文件
python -m mc_translator_mcp check <jar_path>

# 零成本预览：看会翻译哪些模组、多少条文本、预估 token（不调 AI、不写文件）
python -m mc_translator_mcp preview <jar_path>

# 抽样翻译预览质量（会消耗少量 token，不写文件）
python -m mc_translator_mcp dry-run <jar_path> [--limit 20]

# 翻译单个 jar
python -m mc_translator_mcp mod <jar_path> [--batch-size 15] [--force-retranslate]

# 批量翻译目录下所有 jar
python -m mc_translator_mcp dir <directory> [--glob "*.jar"] [--batch-size 15]
```

> 💡 **先 preview 再翻译**：翻译会消耗 token。正式翻译前先跑 `preview` 看工作量和预估消耗，或 `dry-run` 抽样体验翻译质量，再决定是否执行。

## 使用示例

### 在 Trae 对话中使用 MCP 工具
直接对 Trae 说：
> "帮我翻译这个模组：/path/to/mymod.jar"

Trae 会自动调用 MCP 工具的 `translate_mod` 或 `translate_all_mods_in_directory`。

### 本地运行
```bash
# 翻译单个模组（把 <jar_path> 替换成你电脑上的实际路径，下同）
python -m mc_translator_mcp mod "C:/path/to/mods/myzombie.jar" --batch-size 20

# 批量翻译整个 mods 目录
python -m mc_translator_mcp dir "C:/path/to/.minecraft/mods" --glob "*.jar"
```

> 所有 `<jar_path>` / `<directory>` 都请替换成你的**实际绝对路径**，例如 `C:/Users/你的用户名/Desktop/mods/myzombie.jar`。路径中含空格时记得加英文双引号。

## 输出

默认输出到 `output/` 目录，每个模组生成独立资源包：
```
output/
├── mymod-zh-cn/
│   ├── pack.mcmeta
│   └── assets/mymod/lang/zh_cn.json
├── zombie_mod-zh-cn/
│   ├── pack.mcmeta
│   └── assets/zombie_mod/lang/zh_cn.json
└── ...
```

加载方式：将 `output/<modid>-zh-cn/` 文件夹复制到 Minecraft 的 `resourcepacks/` 目录。

## 翻译质量与术语一致性

调用翻译时，会把「这是一个 Minecraft 1.20.1 整合包的模组语言文件」作为上下文注入提示词，并按以下规则约束翻译：

- **Minecraft 官方术语**：`Block`→方块、`Item`→物品、`Inventory`→背包、`Health`→生命、`Craft`→合成、`Enchant`→附魔、`Tool`→工具、`Armor`→盔甲、`Chunk`→区块
- **术语全程一致**：同一英文术语在整个模组内固定用一个中文译名（不会出现一会儿「背包」一会儿「物品栏」），整批条目一起统一后再落盘
- **纯中文输出**：强制要求译文不得残留英文单词（如不允许「沥青铀矿 ore」这种中英混排）；产物会做**残留英文自动纠正**——检测到英文单词的译文自动发起一轮纠正重试
- **漏译自动补翻**：模型偶尔会少返回个别 key，工具会自动对缺失条目发起一轮补翻，保证翻译覆盖率
- **长文本自然化**：wiki/tooltip 等长描述按中文表达习惯意译润色，避免逐字直译的机翻腔
- **知名名词保持通认**：知名模组 / 系列名、科技与化学类专业词保持社区通认译法，不随意直译，如 `Sodium`→钠、`Copper`→铜
- **格式占位符绝不改动**：`{0}`、`%s`、`$variable$`、`§`颜色码、`<modid:item>` 物品标签、`\n` 等原样保留
- **只回传译文**：每条按 `<key>:<中文翻译>` 返回，不做额外解释

### 定制术语表（推荐）

不同模组有自己的社区通认译名（如 Powah 的等级：`Niotic`→钻石、`Spirited`→富生、`Nitro`→下界），通用提示词无法提前知道。为此支持**模组定制术语表**：

1. 编辑项目根目录的 `translator_glossary.json`（或通过 `GLOSSARY_FILE` 环境变量指定其它路径），格式为 `{ "terms": { "英文术语": "强制中文译名" } }`：
   ```json
   {
     "terms": {
       "Niotic": "钻石",
       "Spirited": "富生",
       "Nitro": "下界",
       "Blazing": "烈焰"
     }
   }
   ```
2. 这些术语会注入翻译提示词，要求全模组严格使用定制译名，与官方/社区译名对齐。
3. 文件缺失或格式错误不影响使用（退化为通用提示词）。

> 你也可以直接在 `translator.py` 的 `SYSTEM_PROMPT` 中补充通用规则，改完即生效。

## 核心模块

| 模块 | 功能 |
|------|------|
| `jar_parser.py` | 解析 jar 包结构，发现语言文件 |
| `lang_parser.py` | 解析 .json / .lang / .properties 格式语言文件 |
| `translator.py` | 多供应商批量翻译（custom / agnes / 通义 / DeepSeek）+ Minecraft 术语提示 + 定制术语表 + 漏译补翻 + 残留英文纠正 + 本地缓存 |
| `pack_builder.py` | 生成资源包或改写 jar |
| `mcp_server.py` | MCP 服务器入口，暴露 4 个工具：`translate_mod` / `translate_all_mods_in_directory` / `preview_mod`（零成本预览）/ `dry_run_mod`（抽样预览） |

## 测试

```bash
python -m pytest tests/ -v
```

## 设计要点

1. **资源包优先**：默认生成独立资源包，不破坏原 jar 文件
2. **智能缓存**：相同原文 + modid 的条目只翻译一次，避免重复消耗 token
3. **已有汉化跳过**：检测到已有 zh_cn.json 时自动跳过，避免覆盖社区翻译
4. **批量翻译**：每批最多 BATCH_SIZE 条，一次 API 调用返回全部结果
5. **格式兼容**：支持 `.json`（现代）、`.lang`（传统）与 `.properties`（部分老模组/Java 习惯）三种语言文件格式；`.properties` 源会自动转为 Minecraft 可加载的 `zh_cn.json` 输出
6. **质量自纠**：漏译条目自动补翻、残留英文自动纠正、定制术语表注入，从流程上保证翻译质量与社区译法一致