Mcp Local Translate

io.github.damoqiongqiu由 GitHub 帳號 damoqiongqiu 發布v0.1.11更新於 Oct 24, 2026

Local NLLB translation for 200+ languages. Zero cloud, zero cost, runs entirely on your machine.

已驗證STDIO僅桌面開發者工具AI 與機器學習

概覽

AI 產生的概覽

本機 NLLB-200 翻譯伺服器，讓助理完全在自己的電腦上完成 200 多種語言互譯，不需雲端 API。

可以做什麼
在 200 多種語言之間翻譯文字，支援自動偵測來源語言，語言代碼可用 FLORES-200 精確碼、ISO 639-1 簡碼或中文別名；長文字會依句子邊界分段翻譯後再拼接。列出支援的語言，可依關鍵字篩選查詢。同樣的翻譯與語言列表功能也能以 CLI 指令使用，不必啟動 MCP 伺服器。
適用情境
適合助理需要閱讀或翻譯非母語文件、程式註解或錯誤訊息，又不想把文字貼到線上翻譯工具時；也適合重視隱私、離線使用或需要低資源語言的情境，即使翻譯品質不及頂級雲端服務。
執行需求
透過 npx 在本機執行，需要 Node.js，不需 API Key 或帳號。首次使用時下載 NLLB-200 蒸餾模型（約 600MB）並快取到 CACHE_DIR。首次下載需要網路；HF_ENDPOINT、HF_AUTO_MIRROR 和 HTTPS_PROXY 控制鏡像與代理，TRANSLATE_DEVICE 選擇 cpu 或 webgpu。翻譯時記憶體尖峰約 1.2GB。
安裝前請注意
模型快取後文字留在本機，但首次執行會從 HuggingFace 或鏡像下載模型，會連線到第三方。翻譯品質低於雲端服務，低資源語言尤其明顯。WorkBuddy 使用者必須手動信任自訂連接器，否則不會啟動。CLI 不會讀取 MCP 用戶端設定，需另外傳入設定。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Mcp Local Translate，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

[MCP Local Translate — 跨越语言，无需云。]

MCP Local Translate

[GitHub stars] [npm version] [License: MIT] [TypeScript] [MCP Registry]

🍴 Inspired by shinpr/mcp-local-rag — original architecture patterns by Shinsuke Kagawa

AI 编程助手的本地翻译引擎。基于 NLLB-200 模型，支持 200+ 语言互译——完全离线，数据不离开你的机器。为多语言开发、文档阅读、代码注释翻译而生。

📖 English

特性

  • 200+ 语言互译 基于 Meta NLLB-200 蒸馏模型（600M 参数），覆盖全球绝大多数语言——从主流语言到低资源语言。

  • 完全本地运行 无需 API Key，无需云服务。NLLB-200 模型在本地 CPU 上通过 Transformers.js 推理。数据从不离开你的机器。

  • 智能语言解析 支持 FLORES-200 精确码（zho_Hans）、ISO 639-1 简码（zh）、语言名称（Chinese）、中文别名（中文）——自动映射到正确的模型输入。

  • 长文本分块翻译 长文本在句子边界处自动分块（450 字符/块），每块独立翻译后拼接——突破 NLLB 的 512 token 限制。

  • 零摩擦上手 一条 npx 命令搞定。无需 Docker、Python、GPU。可通过 MCP 或 CLI 使用。

  • 三级镜像回退 自动探测 HF → hf-mirror.com → ModelScope 三级镜像链，国内网络环境下自动找到可用的模型下载源。

快速开始

配置 AI 编程工具

Cursor — 添加到 ~/.cursor/mcp.json：

json
{  "mcpServers": {    "local-translate": {      "command": "npx",      "args": ["-y", "@damoqiongqiu/mcp-local-translate"],      "env": {        "CACHE_DIR": "/path/to/models"      }    }  }}

Codex — 添加到 ~/.codex/config.toml：

toml
[mcp_servers.local-translate]command = "npx"args = ["-y", "@damoqiongqiu/mcp-local-translate"]
[mcp_servers.local-translate.env]CACHE_DIR = "/path/to/models"

Claude Code — 运行以下命令：

bash
claude mcp add local-translate --scope user --env CACHE_DIR=/path/to/models -- npx -y @damoqiongqiu/mcp-local-translate

WorkBuddy — 打开「设置 → 自定义连接器 → 添加自定义连接器」：

json
{  "mcpServers": {    "local-translate": {      "command": "npx",      "args": ["-y", "@damoqiongqiu/mcp-local-translate"],      "env": {        "CACHE_DIR": "/path/to/models"      }    }  }}

⚠️ 首次添加后，必须在「自定义连接器」列表中点击「信任」按钮，否则 MCP 服务器不会启动。这是 WorkBuddy 的安全机制——未经信任的自定义连接器会被静默阻止。

重启工具后即可使用：

你: "把这段文档翻译成中文"助手: [返回翻译结果]
你: "This error message is in Japanese — what does it say?"助手: 那是「データベース接続に失敗しました」——      数据库连接失败。
你: "列出所有支持的翻译语言"助手: 共 204 种语言，包括 中文、英语、日语、法语...

也可直接作为 CLI 使用——无需启动 MCP 服务器：

bash
npx @damoqiongqiu/mcp-local-translate translate "Hello, world!" --source en --target zhnpx @damoqiongqiu/mcp-local-translate list-languages --query "chinese"

就这些。无需 Docker，无需 Python，无需配置服务器。

为什么会有这个项目

你的 AI 编程助手可以帮你写代码，但当你面对非母语的文档、注释、错误日志时，仍然需要跳出编程环境去复制粘贴到在线翻译工具。

隐私。 把代码片段或内部文档粘贴到 Google Translate 本质上是数据泄露。这个工具完全在本地运行——没有人能看到你的文本。

离线可用。 配置完成后无需联网即可使用——飞机上、咖啡店无 WiFi、空气间隙环境。

低资源语言。 NLLB-200 覆盖了 Google Translate 和 DeepL 不支持的小语言（如藏语、维吾尔语、高棉语等）。

成本。 无需为翻译 API 付费。只需一次模型下载（~600MB），然后无限使用。

使用方式

mcp-local-translate 提供两种接口：MCP 服务器（供 AI 编程工具使用）和 CLI（供终端直接使用）。

通过 MCP 使用

MCP 服务器提供 2 个工具：translate 和 list_languages。

翻译文本
"把这段 React hooks 文档翻译成中文""Translate the error message to English""这段日语注释是什么意思？"

translate 工具接受：

参数类型说明
textstring待翻译文本
source_langstring源语言代码（auto 自动检测）
target_langstring目标语言代码

语言代码支持三种格式：

  • FLORES-200 精确码：zho_Hans（简体中文）、eng_Latn（英语）、jpn_Jpan（日语）
  • ISO 639-1 简码：zh、en、ja、fr、de
  • 中文别名：中文、英语、日语、韩语
查看支持的语言
"这个翻译引擎支持多少种语言？""看看有没有藏语"

使用 list_languages 工具，可选 query 参数进行关键词过滤。

作为 CLI 使用

所有 MCP 工具也可以通过 CLI 命令使用——无需启动 MCP 服务器：

bash
# 翻译文本npx @damoqiongqiu/mcp-local-translate translate "Hello, world!" --source en --target zh
# 自动检测源语言npx @damoqiongqiu/mcp-local-translate translate "Bonjour le monde" --source auto --target en
# 查看支持的语言npx @damoqiongqiu/mcp-local-translate list-languages
# 按关键词过滤npx @damoqiongqiu/mcp-local-translate list-languages --query "chinese"

⚠️ CLI 不会读取你的 MCP 客户端配置（mcp.json、config.toml 等）。通过命令行标志或环境变量配置 CLI，如下所示。

工作原理

简要：

  • 语言代码通过三级解析器（精确码 → 别名 → 模糊匹配）映射到 FLORES-200 格式
  • 长文本在句子边界处分块（450 字符/块），每块独立翻译
  • 翻译引擎使用 Transformers.js 加载 NLLB-200 蒸馏模型（600M 参数），在本地 ONNX Runtime 上以 CPU 推理
  • 结果按原始顺序拼接，保持段落和换行结构

详细说明

当你调用 translate 时：

  1. 语言解析：输入的语言代码经过三级解析——先尝试精确 FLORES-200 匹配（zho_Hans），再查 ISO 639-1 别名表（zh → zho_Hans），最后查中文别名表（中文 → zho_Hans）。如果全部失败，进行模糊搜索并给出建议。

  2. 文本预处理：超长文本（>450 字符）在句子边界处拆分（正则 /(?<=[.!?。！？\n])\s+/），确保不截断到句子中间。每块加上源语言和目标语言标记。

  3. 模型推理：每块通过 NLLB-200 蒸馏模型（Xenova/nllb-200-distilled-600M）翻译。模型通过懒加载初始化——首次翻译时下载并加载到内存，后续调用复用同一管道。

  4. 结果拼接：翻译结果按原始块顺序拼接，标记之间的段落和换行得以保留。

配置

环境变量

MCP 服务器仅通过环境变量配置——通过 MCP 客户端的 env 块传入。

环境变量默认值描述
CACHE_DIR系统默认模型缓存目录。NLLB-200 模型（~600MB）自动下载到此。建议使用绝对路径。
HF_ENDPOINThttps://huggingface.coHuggingFace 镜像端点。设置后跳过自动镜像检测。
HF_AUTO_MIRRORtrue自动镜像检测开关。设为 false 禁用。默认开启，首次下载前自动探测三级镜像链：huggingface.co → hf-mirror.com → modelscope.cn。
HTTPS_PROXY（未设置）HTTP 代理地址，用于下载模型（如 http://127.0.0.1:7890）。通过 setGlobalDispatcher 全局生效。
TRANSLATE_DEVICEcpu推理设备。直接传给 Transformers.js。目前仅推荐 cpu。
性能

在 MacBook Pro M1（16GB RAM）、Node.js 22 上测试：

首次启动：

  • 模型下载：1-3 分钟（取决于网络，~600MB）
  • 模型加载：~5s

翻译速度：

  • 短文本（<100 字符）：<1s
  • 中等文本（500 字符）：~3s
  • 长文本（2000 字符）：~12s（4 个分块）

内存：空闲 ~300MB，翻译峰值 ~1.2GB

故障排查

模型下载失败

症状：启动日志中出现 fetch failed 或模型加载超时。

原因与排查：

  1. 网络无法直连 HuggingFace — 如果你在中国大陆或受限网络环境中，直连 huggingface.co 会超时。

    首选方案：不用配置 — mcp-local-translate 默认自动探测三级镜像链：huggingface.co → hf-mirror.com → modelscope.cn，逐级回退直到找到可用镜像。

    备选方案：配置代理：

    json
    "env": {  "HTTPS_PROXY": "http://127.0.0.1:7890"}

    手动指定镜像：

    json
    "env": {  "HF_ENDPOINT": "https://hf-mirror.com"}

  2. 模型文件未写入 CACHE_DIR — 首次运行时会下载约 600MB 的 ONNX 模型。确认 CACHE_DIR 目录存在且包含 Xenova/nllb-200-distilled-600M/ 子目录。如果之前用不同的 CACHE_DIR 下载过模型，更新路径指向已有缓存即可避免重复下载。

  3. npx 缓存了旧版本 — 清除缓存后重启：

    bash
    rm -rf ~/.npm/_npx/

"无效的语言代码"

运行 list_languages 查看所有支持的语言及其代码。语言代码是 FLORES-200 格式（如 zho_Hans、eng_Latn），也可以使用 ISO 639-1 简码（如 zh、en）或中文别名（如 中文、英语）。

翻译速度慢

NLLB-200 在 CPU 上运行，翻译速度取决于你的硬件。长文本会被自动分块处理，每块约 2-3 秒。

常见问题

这真的私密吗？ 是的。在模型下载之后，没有任何数据离开你的机器。可用网络监控验证。

可以离线使用吗？ 可以，只要 NLLB-200 模型已缓存到本地。

与 Google Translate / DeepL 相比如何？ 云端服务翻译质量更高（更大模型、更多训练数据），但需要将数据发送到外部。这个工具用一些质量换取完全隐私和零成本。

支持哪些语言？ NLLB-200 支持 200+ 种语言。运行 list_languages 查看完整列表。

支持方言吗？ NLLB-200 覆盖部分方言变体（如巴西葡萄牙语 por_Latn、拉美西班牙语等），但不像主流语言那样广泛。具体取决于模型训练数据。

翻译质量怎么样？ 对主流语言对（英↔中、英↔法、英↔西等），600M 蒸馏模型提供不错的翻译质量。对低资源语言，质量会下降——可读但不保证优雅。

多用户支持？ 不支持。专为单用户本地访问设计。

开发

从源码构建

bash
git clone https://github.com/damoqiongqiu/mcp-local-translate.gitcd mcp-local-translatepnpm install

代码质量

bash
pnpm run type-check    # TypeScript 检查pnpm run check:fix     # Lint 和格式化pnpm run build         # 编译

项目结构

src/  index.ts              # 入口点 — 路由到 CLI 或 MCP 服务器  server-main.ts        # MCP 服务器启动  server/    index.ts            # MCP 工具处理器（translate、list_languages）    types.ts            # MCP 工具定义  translator/    index.ts            # 核心翻译引擎（NLLB-200 管道、分块、懒加载）    connectivity.ts     # 镜像检测与代理配置    language-codes.ts   # FLORES-200 语言代码与解析器  utils/                # 共享工具skills/                 # 随包发布的 Agent Skills

Agent Skills

Agent Skills 提供优化的提示词，帮助 AI 助手更有效地使用翻译工具：

bash
# Claude Code（项目级别）npx @damoqiongqiu/mcp-local-translate skills install --claude-code
# Claude Code（用户级别）npx @damoqiongqiu/mcp-local-translate skills install --claude-code --global
# Codexnpx @damoqiongqiu/mcp-local-translate skills install --codex

Skills 包括：

  • 语言代码使用：FLORES-200、ISO 639-1、中文别名的映射规则
  • 长文本翻译：自动分块策略和结果解读
  • 国内网络配置：镜像设置和代理配置

贡献

欢迎贡献！参见 CONTRIBUTING.md 了解环境搭建和指南。

许可证

MIT License。免费用于个人和商业用途。

致谢

架构模式参考 mcp-local-rag by Shinsuke Kagawa。使用 Model Context Protocol by Anthropic 和 Transformers.js 构建。翻译模型：NLLB-200 by Meta AI。

來源：README.md，提交 36dbdac

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.1.11最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分