mcp-local-translate

MCP Local Translate

🍴 shinpr/mcp-local-rag に着想を得ています — Shinsuke Kagawa によるオリジナルのアーキテクチャパターン

AI コーディングアシスタントのためのローカル翻訳エンジンです。NLLB-200 モデルを基盤とし、200 以上の言語間の翻訳をサポートします。完全オフラインで動作し、データがマシンの外に出ることはありません。多言語開発、ドキュメントの閲覧、コードコメントの翻訳のために作られています。

📖 英語

特長

• 200 以上の言語間の翻訳 Meta NLLB-200 蒸留モデル（6 億パラメーター）を基盤とし、主要言語から低リソース言語まで、世界のほとんどの言語をカバーします。

• 完全なローカル実行 API キーもクラウドサービスも不要です。NLLB-200 モデルは Transformers.js を通じてローカル CPU で推論します。データがマシンの外に出ることはありません。

• スマートな言語解析 FLORES-200 の正確なコード（zho_Hans）、ISO 639-1 の短縮コード（zh）、言語名（Chinese）、中国語の別名（中文）に対応し、モデルの正しい入力形式に自動変換します。

• 長文の分割翻訳 長文は文の境界で自動的に分割され（1 ブロックあたり 450 文字）、各ブロックを個別に翻訳してから結合します。これにより、NLLB の 512 トークン制限を回避できます。

• すぐに使える手軽さ npx コマンド 1 つで利用できます。Docker、Python、GPU は不要です。MCP または CLI から使用できます。

• 3 段階のミラーへのフォールバック HF → hf-mirror.com → ModelScope の 3 段階のミラーチェーンを自動で検出し、中国国内のネットワーク環境でも利用可能なモデルのダウンロード元を自動で見つけます。

クイックスタート

AI コーディングツールの設定

Cursor — ~/.cursor/mcp.json に追加します：

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

Codex — ~/.codex/config.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 — 以下のコマンドを実行します：

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

WorkBuddy — 「設定 → カスタムコネクター → カスタムコネクターを追加」を開きます：

{
  "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 种语言，包括 中文、英语、日语、法语...

MCP サーバーを起動せずに、CLI として直接使用することもできます：

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

これだけです。Docker も Python もサーバー設定も不要です。

このプロジェクトが生まれた理由

AI コーディングアシスタントはコードを書くのを手伝ってくれます。しかし、母語ではないドキュメント、コメント、エラーログに直面したときは、プログラミング環境を離れてオンライン翻訳ツールにコピー＆ペーストする必要があります。

プライバシー。 コードの一部や社内ドキュメントを Google Translate に貼り付けることは、本質的にデータ漏えいです。このツールは完全にローカルで動作するため、あなたのテキストを誰かに見られることはありません。

オフラインで使用可能。 設定後は、インターネットに接続せずに使用できます。飛行機の中、Wi-Fi のないカフェ、エアギャップ環境でも利用できます。

低リソース言語。 NLLB-200 は、チベット語、ウイグル語、クメール語など、Google Translate や DeepL がサポートしていない小規模言語にも対応します。

コスト。 翻訳 API の料金は不要です。モデルを一度ダウンロード（約 600 MB）すれば、無制限に使用できます。

使用方法

mcp-local-translate は、MCP サーバー（AI コーディングツール向け）と CLI（ターミナルから直接使用）の 2 種類のインターフェースを提供します。

MCP 経由で使用

MCP サーバーは、translate と list_languages の 2 つのツールを提供します。

テキストを翻訳

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

translate ツールが受け取る引数：

言語コードは、次の 3 つの形式に対応しています：

• FLORES-200 の正確なコード：zho_Hans（簡体字中国語）、eng_Latn（英語）、jpn_Jpan（日本語）
• ISO 639-1 の短縮コード：zh、en、ja、fr、de
• 中国語の別名：中文、英语、日语、韩语

対応言語を確認

"这个翻译引擎支持多少种语言？"
"看看有没有藏语"

list_languages ツールを使うと、オプションの query 引数でキーワードによる絞り込みができます。

CLI として使用

すべての MCP ツールは CLI コマンドからも使用できます。MCP サーバーの起動は不要です：

# 翻译文本
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 を設定してください。

仕組み

概要：

• 言語コードは、3 段階のパーサー（正確なコード → 別名 → あいまい検索）を通じて FLORES-200 形式に変換されます
• 長文は文の境界で分割され（1 ブロックあたり 450 文字）、各ブロックが個別に翻訳されます
• 翻訳エンジンは Transformers.js で NLLB-200 蒸留モデル（6 億パラメーター）を読み込み、ローカルの ONNX Runtime 上で CPU 推論します
• 結果は元の順序で結合され、段落や改行の構造が保たれます

詳細

translate を呼び出すと、次の処理が行われます：

1. 言語解析：入力された言語コードを 3 段階で解析します。最初に 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 ブロックを通じて渡してください。

git clone https://github.com/damoqiongqiu/mcp-local-translate.git
cd mcp-local-translate
pnpm install

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 アシスタントが翻訳ツールをより効果的に使えるように最適化されたプロンプトを提供します：

# Claude Code（项目级别）
npx @damoqiongqiu/mcp-local-translate skills install --claude-code

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

# Codex
npx @damoqiongqiu/mcp-local-translate skills install --codex

Skills には以下が含まれます：

• 言語コードの使用：FLORES-200、ISO 639-1、中国語の別名の対応ルール
• 長文の翻訳：自動分割の方法と結果の解釈
• 中国国内のネットワーク設定：ミラーとプロキシの設定

貢献

貢献を歓迎します！環境構築とガイドラインについては、CONTRIBUTING.md を参照してください。

ライセンス

MIT License。個人利用および商用利用は無料です。

謝辞

アーキテクチャパターンは、Shinsuke Kagawa による mcp-local-rag を参考にしています。Anthropic の Model Context Protocol と Transformers.js を使用して構築されています。翻訳モデル：NLLB-200（Meta AI）。