paraglide-messages-mcp

paraglide-messages-mcp

Paraglide JS／inlang メッセージファイルを、OpenAI Batch API 経由で翻訳するステートレスな MCP サービスです。

OpenAI が非同期で翻訳します。MCP クライアントはジョブを送信し、後から結果を取得します。OpenAI が処理している間に、クライアントとサーバーが切断または再起動しても問題ありません。各リクエストには、使用状況のコンテキストとしてフラットなメッセージキー、原文、既存の翻訳文、プレースホルダー、スタイルの概要、既存の翻訳文の小規模なサンプルが含まれます。デフォルトは gpt-6-luna で、reasoning.effort: "low"（「Luna light」）を使用します。

Node.js 22.12 以降と、設定された Batch モデルを利用できる OpenAI API キーが必要です。キーがなくても、プロジェクトの確認と手動修正の保存は可能です。

接続

{
  "mcpServers": {
    "paraglide": {
      "command": "npx",
      "args": [
        "-y", "paraglide-messages-mcp",
        "--project", "./project.inlang",
        "--translation-style", "Concise product UI; informal address; preserve brand terms."
      ],
      "env": { "OPENAI_API_KEY": "<your API key>" }
    }
  }
}

クライアントのシークレット／環境設定を使ってキーを指定してください。認証情報をコミットしないでください。.inlang ディレクトリを検出できる場合、--project は省略できます。--model <id> でデフォルトを上書きできます。--jobs-dir <path> でローカルのジョブディレクトリを上書きできます。

翻訳

1. project_info を呼び出して、ロケールと未翻訳数を確認します。

2. 安定した jobId を指定して、start_translation_job を呼び出します。例：

   { "jobId": "checkout-fr-2026-10-07", "targetLocales": ["fr"], "prefix": "checkout_" }
   

   ソース以外のすべてのロケールを対象にする場合は、targetLocales を省略します。ソースはデフォルトでプロジェクトのベースロケールになります。カタログ全体を対象にする場合は、prefix を省略します。既存の翻訳も更新するには、mode: "all" を使用します。ジョブごとの translationStyle は、起動時の概要を上書きします。

3. 返された ID を保存し、定期的に get_translation_job を呼び出します。Batch ジョブの完了期限は 24 時間です。ツール呼び出しは接続を開いたまま待機せず、1 回だけ状態を確認します。エラー後も同じ ID を再利用してください。再起動後は、OpenAI を呼び出さずに list_translation_jobs でジョブを検索できます。

4. Batch ジョブが終了すると、結果の取得時に出力／エラーファイルをアーカイブし、個々の翻訳を検証して、承認された値をロケールファイルにマージします。saved、failed、lastError、cleanedUp を確認してください。リモートのステータスが completed でも、すべての値が保存されたとは限りません。ツールの応答に含まれる失敗の詳細は最大 50 件です。ジョブレコードにはすべての結果が記録されます。失敗または競合が発生したメッセージは、save_translations で修正するか、新しい範囲指定ジョブで翻訳できます。

対象範囲が空の場合、API リクエストなしでローカル処理が完了します。同じ ID を異なるオプションで再利用すると、拒否されます。新しい作業には新しい ID を使用してください。既存の ID で再試行すると、元のスナップショットから再開されます。

耐久性とクリーンアップ

ジョブのスナップショットと ID は project.inlang/.paraglide-batches/ にアトミックに永続化されます。このディレクトリは永続ストレージに保持し、ソース管理から除外してください。メッセージテキストとアーカイブされたモデル出力が含まれています。API キーがジョブレコードに保存されることはありません。ロックにより、同一ホスト上のプロセス間でジョブの調整とカタログへの書き込みが直列化されます。バッチ実行中に行われたソースまたはターゲットの編集は保持され、競合として報告されます。中断された収集の後でも、ロケールごとのマージを再実行できます。

失われたバッチ作成応答は、OpenAI のバッチメタデータと入力ファイル ID を使って調整されます。不確かな送信が自動的に再試行されることはないため、有料バッチの重複を防げます。調整の結果、一致するバッチが見つからない場合、ジョブは保留状態のまま lastError を報告します。代替の作業を送信するかどうかを判断する前に、OpenAI で確認してください。OpenAI はモデルの利用可否を非同期で検証します。未対応のモデルはバッチエラーとして報告されます。

「完了したバッチを閉じる」操作はありません。結果が安全にアーカイブされ、適用された後、サービスはリモートの入力ファイル、出力ファイル、エラーファイルを削除します。クリーンアップに失敗しても、再開できます。フォールバックとして、アップロードされたファイルと生成されたファイルはいずれも 30 日後に期限切れになります。期限切れになる前に収集してください。cancel_translation_job は、OpenAI にキャンセルを送信する前にキャンセルを記録します。キャンセルには最大 10 分かかる場合があります。終端状態になり、cleanedUp: true になるまで収集を続けてください。キャンセル済みまたは期限切れのバッチで生成された成功済みの部分的な結果も検証され、適用されます。

無人で収集するには、独自のスケジューラーを使って次のコマンドを定期的に実行してください。

npx paraglide-messages-mcp --project ./project.inlang --resume

未完了のローカルジョブをそれぞれ 1 回調整し、JSON の概要を出力して終了します。MCP セッションにひも付いたタイマーやワーカーは残りません。収集エラーまたは翻訳の拒否がある場合は、ゼロ以外の終了コードを返します。

ツール

ツール	目的
project_info	ロケール、ソース、件数、起動時のスタイル概要
list_message_keys	プレフィックス／ステータスで絞り込んだフラットなキー。カーソルページネーション対応
get_messages	キーまたはプレフィックスに対応するメッセージ値
search_messages	テキストとキーの部分文字列を検索
save_translations	既存キーに対する検証済みの修正
start_translation_job	永続的な OpenAI Batch ジョブを送信
get_translation_job	ジョブを調整し、収集してクリーンアップ
list_translation_jobs	ローカルジョブの概要。カーソルページネーション対応
cancel_translation_job	部分的な結果を保持してキャンセルを要求

以前のエージェントによる翻訳ループ、ワークフロープロンプト、重複リソース、カタログ／ロケールを破壊的に管理するツールは、MCP のインターフェースから削除されました。既存の TranslationService ライブラリヘルパーは、必要とする呼び出し元が引き続き利用できます。MCP による保存では、検証のバイパスや任意の新規キー作成は利用できなくなりました。

ステートレス HTTP

CLI は SDK v2 の serveStdio を使用します。ライブラリでは、Web 標準の HTTP ハンドラーもエクスポートされています。

import { createHandler } from "paraglide-messages-mcp";
const handler = createHandler("/workspace/project.inlang", { translationStyle: "Concise UI" });
// Mount handler.fetch(Request) on your HTTP runtime; call handler.close() at shutdown.

このハンドラーはリクエストごとに新しい MCP サーバーを作成し、初期化やセッション ID を必要としない 2026-07-28 プロトコルに対応しています。レガシークライアントには SDK の互換性機能を通じてステートレスに対応します。デプロイ時には、SDK HTTP ガイドの説明に従い、fetch の前段に認証と Host／Origin チェックを配置する必要があります。ファイルシステムストアは、単一ホスト、または永続ストレージを使う単一ライターのデプロイをサポートします。複数ホストのレプリカには、共有トランザクション対応のジョブ／カタログストアと分散ロックが必要です。

対応するメッセージ形式については COMPATIBILITY.md、アーキテクチャとテストについては DEVELOPMENT.md を参照してください。オプションの エージェントスキルでは、バッチワークフローについて説明しています。

ライセンス

MIT