{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/banner.jpg\" alt=\"MCP Local Translate — 跨越语言，无需云。\" width=\"600\" />\n</p>\n\n# MCP Local Translate\n\n[![GitHub stars](https://img.shields.io/github/stars/damoqiongqiu/mcp-local-translate?style=social)](https://github.com/damoqiongqiu/mcp-local-translate)\n[![npm version](https://img.shields.io/npm/v/@damoqiongqiu/mcp-local-translate.svg)](https://www.npmjs.com/package/@damoqiongqiu/mcp-local-translate)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/)\n\n> 🍴 Inspired by [shinpr/mcp-local-rag](https://github.com/shinpr/mcp-local-rag) — original architecture patterns by [Shinsuke Kagawa](https://github.com/shinpr)\n>\n> AI 编程助手的本地翻译引擎。基于 NLLB-200 模型，支持 200+ 语言互译——完全离线，数据不离开你的机器。为多语言开发、文档阅读、代码注释翻译而生。\n\n📖 [English](README_EN.md)\n\n---\n\n## 特性\n\n- **200+ 语言互译**\n  基于 Meta NLLB-200 蒸馏模型（600M 参数），覆盖全球绝大多数语言——从主流语言到低资源语言。\n\n- **完全本地运行**\n  无需 API Key，无需云服务。NLLB-200 模型在本地 CPU 上通过 Transformers.js 推理。数据从不离开你的机器。\n\n- **智能语言解析**\n  支持 FLORES-200 精确码（`zho_Hans`）、ISO 639-1 简码（`zh`）、语言名称（`Chinese`）、中文别名（`中文`）——自动映射到正确的模型输入。\n\n- **长文本分块翻译**\n  长文本在句子边界处自动分块（450 字符/块），每块独立翻译后拼接——突破 NLLB 的 512 token 限制。\n\n- **零摩擦上手**\n  一条 `npx` 命令搞定。无需 Docker、Python、GPU。可通过 MCP 或 CLI 使用。\n\n- **三级镜像回退**\n  自动探测 HF → hf-mirror.com → ModelScope 三级镜像链，国内网络环境下自动找到可用的模型下载源。\n\n---\n\n## 快速开始\n\n### 配置 AI 编程工具\n\n**Cursor** — 添加到 `~/.cursor/mcp.json`：\n```json\n{\n  \"mcpServers\": {\n    \"local-translate\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@damoqiongqiu/mcp-local-translate\"],\n      \"env\": {\n        \"CACHE_DIR\": \"/path/to/models\"\n      }\n    }\n  }\n}\n```\n\n**Codex** — 添加到 `~/.codex/config.toml`：\n```toml\n[mcp_servers.local-translate]\ncommand = \"npx\"\nargs = [\"-y\", \"@damoqiongqiu/mcp-local-translate\"]\n\n[mcp_servers.local-translate.env]\nCACHE_DIR = \"/path/to/models\"\n```\n\n**Claude Code** — 运行以下命令：\n```bash\nclaude mcp add local-translate --scope user --env CACHE_DIR=/path/to/models -- npx -y @damoqiongqiu/mcp-local-translate\n```\n\n**WorkBuddy** — 打开「设置 → 自定义连接器 → 添加自定义连接器」：\n\n```json\n{\n  \"mcpServers\": {\n    \"local-translate\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@damoqiongqiu/mcp-local-translate\"],\n      \"env\": {\n        \"CACHE_DIR\": \"/path/to/models\"\n      }\n    }\n  }\n}\n```\n\n> ⚠️ **首次添加后，必须在「自定义连接器」列表中点击「信任」按钮**，否则 MCP 服务器不会启动。这是 WorkBuddy 的安全机制——未经信任的自定义连接器会被静默阻止。\n\n重启工具后即可使用：\n\n```\n你: \"把这段文档翻译成中文\"\n助手: [返回翻译结果]\n\n你: \"This error message is in Japanese — what does it say?\"\n助手: 那是「データベース接続に失敗しました」——\n      数据库连接失败。\n\n你: \"列出所有支持的翻译语言\"\n助手: 共 204 种语言，包括 中文、英语、日语、法语...\n```\n\n**也可直接作为 CLI 使用——无需启动 MCP 服务器：**\n\n```bash\nnpx @damoqiongqiu/mcp-local-translate translate \"Hello, world!\" --source en --target zh\nnpx @damoqiongqiu/mcp-local-translate list-languages --query \"chinese\"\n```\n\n就这些。无需 Docker，无需 Python，无需配置服务器。\n\n---\n\n## 为什么会有这个项目\n\n你的 AI 编程助手可以帮你写代码，但当你面对非母语的文档、注释、错误日志时，仍然需要跳出编程环境去复制粘贴到在线翻译工具。\n\n**隐私。** 把代码片段或内部文档粘贴到 Google Translate 本质上是数据泄露。这个工具完全在本地运行——没有人能看到你的文本。\n\n**离线可用。** 配置完成后无需联网即可使用——飞机上、咖啡店无 WiFi、空气间隙环境。\n\n**低资源语言。** NLLB-200 覆盖了 Google Translate 和 DeepL 不支持的小语言（如藏语、维吾尔语、高棉语等）。\n\n**成本。** 无需为翻译 API 付费。只需一次模型下载（~600MB），然后无限使用。\n\n---\n\n## 使用方式\n\nmcp-local-translate 提供两种接口：**MCP 服务器**（供 AI 编程工具使用）和 **CLI**（供终端直接使用）。\n\n### 通过 MCP 使用\n\nMCP 服务器提供 2 个工具：`translate` 和 `list_languages`。\n\n#### 翻译文本\n\n```\n\"把这段 React hooks 文档翻译成中文\"\n\"Translate the error message to English\"\n\"这段日语注释是什么意思？\"\n```\n\n`translate` 工具接受：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `text` | `string` | 待翻译文本 |\n| `source_lang` | `string` | 源语言代码（`auto` 自动检测） |\n| `target_lang` | `string` | 目标语言代码 |\n\n语言代码支持三种格式：\n- **FLORES-200 精确码**：`zho_Hans`（简体中文）、`eng_Latn`（英语）、`jpn_Jpan`（日语）\n- **ISO 639-1 简码**：`zh`、`en`、`ja`、`fr`、`de`\n- **中文别名**：`中文`、`英语`、`日语`、`韩语`\n\n#### 查看支持的语言\n\n```\n\"这个翻译引擎支持多少种语言？\"\n\"看看有没有藏语\"\n```\n\n使用 `list_languages` 工具，可选 `query` 参数进行关键词过滤。\n\n### 作为 CLI 使用\n\n所有 MCP 工具也可以通过 CLI 命令使用——无需启动 MCP 服务器：\n\n```bash\n# 翻译文本\nnpx @damoqiongqiu/mcp-local-translate translate \"Hello, world!\" --source en --target zh\n\n# 自动检测源语言\nnpx @damoqiongqiu/mcp-local-translate translate \"Bonjour le monde\" --source auto --target en\n\n# 查看支持的语言\nnpx @damoqiongqiu/mcp-local-translate list-languages\n\n# 按关键词过滤\nnpx @damoqiongqiu/mcp-local-translate list-languages --query \"chinese\"\n```\n\n> ⚠️ CLI **不会**读取你的 MCP 客户端配置（`mcp.json`、`config.toml` 等）。通过命令行标志或环境变量配置 CLI，如下所示。\n\n---\n\n## 工作原理\n\n**简要：**\n- 语言代码通过三级解析器（精确码 → 别名 → 模糊匹配）映射到 FLORES-200 格式\n- 长文本在句子边界处分块（450 字符/块），每块独立翻译\n- 翻译引擎使用 Transformers.js 加载 NLLB-200 蒸馏模型（600M 参数），在本地 ONNX Runtime 上以 CPU 推理\n- 结果按原始顺序拼接，保持段落和换行结构\n\n### 详细说明\n\n当你调用 `translate` 时：\n\n1. **语言解析**：输入的语言代码经过三级解析——先尝试精确 FLORES-200 匹配（`zho_Hans`），再查 ISO 639-1 别名表（`zh` → `zho_Hans`），最后查中文别名表（`中文` → `zho_Hans`）。如果全部失败，进行模糊搜索并给出建议。\n\n2. **文本预处理**：超长文本（>450 字符）在句子边界处拆分（正则 `/(?<=[.!?。！？\\n])\\s+/`），确保不截断到句子中间。每块加上源语言和目标语言标记。\n\n3. **模型推理**：每块通过 NLLB-200 蒸馏模型（`Xenova/nllb-200-distilled-600M`）翻译。模型通过懒加载初始化——首次翻译时下载并加载到内存，后续调用复用同一管道。\n\n4. **结果拼接**：翻译结果按原始块顺序拼接，标记之间的段落和换行得以保留。\n\n---\n\n## 配置\n\n### 环境变量\n\nMCP 服务器仅通过环境变量配置——通过 MCP 客户端的 `env` 块传入。\n\n| 环境变量 | 默认值 | 描述 |\n|---------|--------|------|\n| `CACHE_DIR` | 系统默认 | 模型缓存目录。NLLB-200 模型（~600MB）自动下载到此。建议使用绝对路径。 |\n| `HF_ENDPOINT` | `https://huggingface.co` | HuggingFace 镜像端点。设置后跳过自动镜像检测。 |\n| `HF_AUTO_MIRROR` | `true` | 自动镜像检测开关。设为 `false` 禁用。默认开启，首次下载前自动探测三级镜像链：`huggingface.co` → `hf-mirror.com` → `modelscope.cn`。 |\n| `HTTPS_PROXY` | （未设置） | HTTP 代理地址，用于下载模型（如 `http://127.0.0.1:7890`）。通过 `setGlobalDispatcher` 全局生效。 |\n| `TRANSLATE_DEVICE` | `cpu` | 推理设备。直接传给 Transformers.js。目前仅推荐 `cpu`。 |\n\n---\n\n<details>\n<summary><strong>性能</strong></summary>\n\n在 MacBook Pro M1（16GB RAM）、Node.js 22 上测试：\n\n**首次启动**：\n- 模型下载：1-3 分钟（取决于网络，~600MB）\n- 模型加载：~5s\n\n**翻译速度**：\n- 短文本（<100 字符）：<1s\n- 中等文本（500 字符）：~3s\n- 长文本（2000 字符）：~12s（4 个分块）\n\n**内存**：空闲 ~300MB，翻译峰值 ~1.2GB\n\n</details>\n\n<details>\n<summary><strong>故障排查</strong></summary>\n\n### 模型下载失败\n\n**症状**：启动日志中出现 `fetch failed` 或模型加载超时。\n\n**原因与排查**：\n\n1. **网络无法直连 HuggingFace** — 如果你在中国大陆或受限网络环境中，直连 `huggingface.co` 会超时。\n\n   **首选方案：不用配置** — mcp-local-translate 默认自动探测三级镜像链：`huggingface.co` → `hf-mirror.com` → `modelscope.cn`，逐级回退直到找到可用镜像。\n\n   **备选方案：配置代理**：\n   ```json\n   \"env\": {\n     \"HTTPS_PROXY\": \"http://127.0.0.1:7890\"\n   }\n   ```\n\n   **手动指定镜像**：\n   ```json\n   \"env\": {\n     \"HF_ENDPOINT\": \"https://hf-mirror.com\"\n   }\n   ```\n\n2. **模型文件未写入 `CACHE_DIR`** — 首次运行时会下载约 600MB 的 ONNX 模型。确认 `CACHE_DIR` 目录存在且包含 `Xenova/nllb-200-distilled-600M/` 子目录。如果之前用不同的 `CACHE_DIR` 下载过模型，更新路径指向已有缓存即可避免重复下载。\n\n3. **npx 缓存了旧版本** — 清除缓存后重启：\n   ```bash\n   rm -rf ~/.npm/_npx/\n   ```\n\n### \"无效的语言代码\"\n\n运行 `list_languages` 查看所有支持的语言及其代码。语言代码是 FLORES-200 格式（如 `zho_Hans`、`eng_Latn`），也可以使用 ISO 639-1 简码（如 `zh`、`en`）或中文别名（如 `中文`、`英语`）。\n\n### 翻译速度慢\n\nNLLB-200 在 CPU 上运行，翻译速度取决于你的硬件。长文本会被自动分块处理，每块约 2-3 秒。\n\n</details>\n\n<details>\n<summary><strong>常见问题</strong></summary>\n\n**这真的私密吗？**\n是的。在模型下载之后，没有任何数据离开你的机器。可用网络监控验证。\n\n**可以离线使用吗？**\n可以，只要 NLLB-200 模型已缓存到本地。\n\n**与 Google Translate / DeepL 相比如何？**\n云端服务翻译质量更高（更大模型、更多训练数据），但需要将数据发送到外部。这个工具用一些质量换取完全隐私和零成本。\n\n**支持哪些语言？**\nNLLB-200 支持 200+ 种语言。运行 `list_languages` 查看完整列表。\n\n**支持方言吗？**\nNLLB-200 覆盖部分方言变体（如巴西葡萄牙语 `por_Latn`、拉美西班牙语等），但不像主流语言那样广泛。具体取决于模型训练数据。\n\n**翻译质量怎么样？**\n对主流语言对（英↔中、英↔法、英↔西等），600M 蒸馏模型提供不错的翻译质量。对低资源语言，质量会下降——可读但不保证优雅。\n\n**多用户支持？**\n不支持。专为单用户本地访问设计。\n\n</details>\n\n<details>\n<summary><strong>开发</strong></summary>\n\n### 从源码构建\n\n```bash\ngit clone https://github.com/damoqiongqiu/mcp-local-translate.git\ncd mcp-local-translate\npnpm install\n```\n\n### 代码质量\n\n```bash\npnpm run type-check    # TypeScript 检查\npnpm run check:fix     # Lint 和格式化\npnpm run build         # 编译\n```\n\n### 项目结构\n\n```\nsrc/\n  index.ts              # 入口点 — 路由到 CLI 或 MCP 服务器\n  server-main.ts        # MCP 服务器启动\n  server/\n    index.ts            # MCP 工具处理器（translate、list_languages）\n    types.ts            # MCP 工具定义\n  translator/\n    index.ts            # 核心翻译引擎（NLLB-200 管道、分块、懒加载）\n    connectivity.ts     # 镜像检测与代理配置\n    language-codes.ts   # FLORES-200 语言代码与解析器\n  utils/                # 共享工具\nskills/                 # 随包发布的 Agent Skills\n```\n\n</details>\n\n---\n\n## Agent Skills\n\n[Agent Skills](https://agentskills.io/) 提供优化的提示词，帮助 AI 助手更有效地使用翻译工具：\n\n```bash\n# Claude Code（项目级别）\nnpx @damoqiongqiu/mcp-local-translate skills install --claude-code\n\n# Claude Code（用户级别）\nnpx @damoqiongqiu/mcp-local-translate skills install --claude-code --global\n\n# Codex\nnpx @damoqiongqiu/mcp-local-translate skills install --codex\n```\n\nSkills 包括：\n- **语言代码使用**：FLORES-200、ISO 639-1、中文别名的映射规则\n- **长文本翻译**：自动分块策略和结果解读\n- **国内网络配置**：镜像设置和代理配置\n\n---\n\n## 贡献\n\n欢迎贡献！参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境搭建和指南。\n\n## 许可证\n\nMIT License。免费用于个人和商业用途。\n\n## 致谢\n\n架构模式参考 [mcp-local-rag](https://github.com/damoqiongqiu/mcp-local-rag) by [Shinsuke Kagawa](https://github.com/shinpr)。使用 [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic 和 [Transformers.js](https://huggingface.co/docs/transformers.js) 构建。翻译模型：[NLLB-200](https://ai.meta.com/research/no-language-left-behind/) by Meta AI。\n",
  "bytes": 9099,
  "sha": "f1a67dafe25aace035c94f333ce4161804aaecbcae6f02f3c82a20744cfe1a0c",
  "repo_slug": "damoqiongqiu/mcp-local-translate",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_damoqiongqiu_mcp_local_transla_45d2100e/readme"
}