Skip to main content
Glama
Sign In
deenesjakoruzh
mc-translator-mcp

mc-translator-mcp

by dcd887
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

mc-translator-mcp

Minecraft 模组中文翻译 MCP 工具

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

安装

cd mc-translator-mcp
pip install -e .

Related MCP server: NetEase ModSDK MCP Server

配置

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

cp .env.example .env

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

# 方式 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. 先确认程序能跑（不联网）：

    python -m mc_translator_mcp --help

    能看到命令帮助说明安装正常。若报 No module named mc_translator_mcp，说明没装好或没在项目目录下运行。

  2. 再确认 API Key 被正确加载：

    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 服务器（推荐）

python -m mc_translator_mcp

在 Trae/Claude Desktop 中配置 MCP server：

{
  "mcpServers": {
    "mc-translator-mcp": {
      "command": "python",
      "args": ["-m", "mc_translator_mcp"]
    }
  }
}

CLI 模式

# 检查 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。

本地运行

# 翻译单个模组（把 <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": { "英文术语": "强制中文译名" } }：

    {
  "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（抽样预览）

测试

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. 质量自纠：漏译条目自动补翻、残留英文自动纠正、定制术语表注入，从流程上保证翻译质量与社区译法一致

Available Tools

4 tools
dry_run_modA

预览翻译效果：解析单个模组并抽样翻译一小部分，不写入任何文件。

注意：本工具会调用 AI 翻译 API 并消耗少量 token（最多 limit 条样例）， 只用来快速感受翻译质量，不会生成资源包、不改动原 jar。

Args: jar_path: 模组 jar 文件的绝对路径 limit: 最多预览（抽样翻译）的条目总数（默认 20） batch_size: 每批翻译的词条数（默认 15） Returns: 预览 JSON，含原文-译文对照样例

NameRequiredDescriptionDefault
limitNo
jar_pathYes
batch_sizeNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the behavioral burden and largely does: it discloses that no files are written, that the AI translation API is called and tokens are consumed (bounded by limit), that no resource pack is generated, and that the source jar is untouched. It omits auth requirements, rate limits, and failure behavior, but the mutation-and-cost profile is unusually well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the no-write guarantee in bold, followed by cost warning and args/returns blocks. The structure is easy to scan; the cost warning is slightly verbose and the 'Returns' note partly duplicates the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter tool with an output schema, the description covers the essential unknowns: side effects (none on disk), cost (token spend), and parameter meaning. Return-value detail is minimal, which is acceptable given the output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description is the only source of parameter meaning, and it documents all three: jar_path as an absolute path, limit as the max sampled entries (default 20), and batch_size as entries per batch (default 15). This compensates well for the empty schema descriptions, though the relationship between limit and batch_size could be spelled out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('解析单个模组并抽样翻译') plus the scope constraint of not writing files, which lets an agent distinguish it from translate_mod. However it never explicitly contrasts itself with the closest sibling, preview_mod, whose name suggests overlapping purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context: '只用来快速感受翻译质量' (only for quickly sensing translation quality) and warns about token consumption. It does not, however, name the alternative tool to use when the agent actually wants a full translation or a written output.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

preview_modA

（零成本）预览单个模组的汉化范围：列出每个语言文件、条目数与预估 token。

只做 jar 扫描与文本解析，不调用任何 AI 翻译 API、不消耗 token、不写任何文件， 用于在真正翻译前评估工作量与费用。

Args: jar_path: 模组 jar 文件的绝对路径 Returns: 预览摘要 JSON（含每个 modid 的格式、条目数、是否已有 zh_cn、社区估算 token）

NameRequiredDescriptionDefault
jar_pathYes

Output Schema

NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden; it declares read-only scanning, no AI API calls, no token consumption, and no file writes. It also states the return content is a preview summary JSON, giving a strong safety and behavior profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the key purpose and scope, then supporting details and Args/Returns. Slight redundancy between '零成本' and '不消耗 token' keeps it from being maximally tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description need not detail return values, and it still summarizes them. It covers the single input, safety behavior, and usage context, leaving no major gaps for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one parameter with 0% description coverage, but the description defines jar_path as the absolute path to a mod jar file. This compensates adequately, though no further path constraints are given.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: preview a single mod's localization scope, listing language files, entry counts, and estimated tokens. It is clear but does not explicitly name or differentiate itself from siblings such as dry_run_mod, so sibling differentiation remains implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear context: use before actual translation to assess workload and cost. It also states what it does not do (no AI API, no token use, no file writes), but it does not explicitly say when to choose it over dry_run_mod or translate_mod.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

translate_all_mods_in_directoryB

批量翻译目录下所有模组 jar 包。

Args: directory: 包含模组 jar 的目录路径 glob_pattern: jar 文件匹配模式（默认 *.jar） batch_size: 每批翻译的词条数 force_retranslate: 强制重新翻译 Returns: 批量翻译汇总

NameRequiredDescriptionDefault
directoryYes
batch_sizeNo
glob_patternNo*.jar
force_retranslateNo

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about side effects: whether jars are modified in place, whether existing translations are backed up, whether the translation backend imposes rate limits, or whether the operation is reversible. Only the force_retranslate flag hints at overwrite behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose sentence is front-loaded and the Args list is terse with no filler. The trailing Returns line is minimal, which is acceptable since an output schema exists, though it adds little.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no explanation, and all four parameters are covered. What is missing is the mutation profile of a batch file-processing tool with no annotations: overwrite/backup behavior and any safety or ordering caveats an agent should know before running it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% (titles only), so the description must compensate, and it does define all four parameters meaningfully: directory path, glob matching pattern, entries per batch, and force-retranslate. It does not explain the acceptable values or performance implications of batch_size, but coverage of the semantics is solid.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: batch-translating all mod jars under a directory. The scope word ('all mods in a directory' / 目录下所有) implicitly distinguishes it from the singular translate_mod sibling. It stops short of naming the siblings, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus preview_mod, dry_run_mod, or translate_mod. The batch scope is implied by the name and purpose line, but there is no explicit condition, prerequisite, or exclusion telling an agent which tool to pick.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

translate_modA

翻译单个 Minecraft 模组 jar 包，生成中文资源包。

Args: jar_path: 模组 jar 文件的绝对路径（如 C:...\mymod-1.2.0.jar） batch_size: 每批翻译的词条数（默认 15，越大越快但单次请求更长） force_retranslate: 强制重新翻译（忽略缓存，慎用） Returns: 翻译结果摘要（包含每个模组的输出路径）

NameRequiredDescriptionDefault
jar_pathYes
batch_sizeNo
force_retranslateNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the full burden. It does disclose useful behavior: force_retranslate ignores the cache ('慎用' = use with caution) and batch_size trades speed against request length. It omits permissions, network/API dependency, and whether the original jar is modified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by a compact Args/Returns block. Every line carries information; no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the Returns note is redundant but harmless. However, for a tool with no annotations that presumably performs network translation and file output, the description never states prerequisites, failure modes, or side effects on disk, leaving notable behavioral gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description is the only source of parameter meaning, and it delivers for all three: jar_path is an absolute path with an example format, batch_size gives the default and its speed/latency tradeoff, and force_retranslate explains the cache-bypass consequence and cautions against it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('translate a single Minecraft mod jar, generate a Chinese resource pack'), so the agent knows exactly what the tool produces. It does not, however, distinguish itself from its siblings (preview_mod, dry_run_mod) which likely operate on the same kind of input.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to use this tool versus preview_mod, dry_run_mod, or translate_all_mods_in_directory. An agent must infer that a single-jar translate is distinct from a dry-run or batch translate without any explicit routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observeddry_run_mod
    • First observedpreview_mod
    • First observedtranslate_all_mods_in_directory
    • First observedtranslate_mod
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation4/5

preview_mod and dry_run_mod both preview a single mod, but one is a zero-cost scope review and the other samples actual AI translations, so the cost/AI distinction prevents most confusion. translate_mod and translate_all_mods_in_directory are clearly distinguished by single vs batch scope.

Naming Consistency4/5

All tool names use snake_case and follow an action_mod pattern, which is mostly consistent. The only minor deviation is dry_run_mod, which uses a compound action phrase rather than a simple verb_noun, and translate_all_mods_in_directory is noticeably longer than the others.

Tool Count5/5

Four tools are well-scoped for a Minecraft mod translation workflow: preview scope, preview quality, translate one, and translate many. No tool feels redundant, and the count matches the domain without being thin or bloated.

Completeness4/5

The surface covers the core translation lifecycle from cost estimation and sampled preview through single-mod and batch translation. Minor gaps remain around explicit output/language configuration or result validation, but agents can work around these.

Resources

Related MCP Connectors

Related MCP Servers