paraglide-messages-mcp

paraglide-messages-mcp

通过 OpenAI Batch API 翻译 Paraglide JS / inlang 消息文件的无状态 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. 调用 start_translation_job 并提供稳定的 jobId，例如：

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

   若要翻译源语言以外的所有语言区域，请省略 targetLocales。源语言默认为项目的基础语言区域。若要翻译整个目录，请省略 prefix。使用 mode: "all" 刷新现有译文。每个任务的 translationStyle 会覆盖启动时设置的风格说明。

3. 保存返回的 ID，并定期调用 get_translation_job。Batch 任务的完成时限为 24 小时；工具调用只会检查一次，而不是保持连接打开。发生错误后请重用同一 ID。重启后可通过 list_translation_jobs 查找任务，无需调用 OpenAI。

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

该命令会协调每个未完成的本地任务一次，打印 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	请求取消，并保留部分结果

旧版 Agent 翻译循环、工作流提示词、重复资源，以及具有破坏性的目录／语言区域管理工具已从 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 服务，并支持 2026-07-28 协议，无需初始化或会话 ID。旧版客户端通过 SDK 兼容层以无状态方式提供服务。部署时必须按照 SDK HTTP 指南中的说明，在 fetch 之前挂载身份验证和 Host／Origin 检查。文件系统存储支持单主机，或持久化的单写入者部署；多主机副本需要共享的事务性任务／目录存储和分布式锁。

有关支持的消息格式，请参阅 COMPATIBILITY.md；有关架构和测试，请参阅 DEVELOPMENT.md。可选的 Agent 技能介绍了批处理工作流。

许可证

MIT