paraglide-messages-mcp

paraglide-messages-mcp

Stateless MCP service for translating Paraglide JS / inlang message files through the OpenAI Batch API.

OpenAI does the translation asynchronously. The MCP client submits a job and later collects it; the client and server can disconnect or restart while OpenAI works. Each request includes flat message keys as usage context, source text, existing target text, placeholders, a style brief, and a small sample of existing target copy. The default is gpt-6-luna with reasoning.effort: "low" (“Luna light”).

Requires Node.js 22.12+ and an OpenAI API key with access to the configured Batch model. Inspecting projects and saving manual corrections work without a key.

Connect

{
  "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>" }
    }
  }
}

Use your client's secret/environment configuration to supply the key; don't commit credentials. --project is optional when there is a discoverable .inlang directory. --model <id> overrides the default. --jobs-dir <path> overrides the local job directory.

Translate

1. Call project_info to inspect locales and missing counts.

2. Call start_translation_job with a stable jobId, for example:

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

   Omit targetLocales for every locale except the source. The source defaults to the project base locale. Omit prefix for the whole catalog. Use mode: "all" to refresh existing translations. A per-job translationStyle overrides the startup brief.

3. Keep the returned ID and periodically call get_translation_job. Batch jobs have a 24-hour completion window; a tool call checks once instead of holding a connection open. Reuse the same ID after errors. list_translation_jobs discovers jobs after a restart without calling OpenAI.

4. On a terminal batch, collection archives output/error files, validates individual translations, and merges accepted values into the locale files. Check saved, failed, lastError, and cleanedUp; a remote completed status alone does not mean everything was saved. Failure details are capped at 50 in tool responses; the job record contains every outcome. Failed or conflicted messages can be corrected with save_translations or translated in a new scoped job.

An empty scope finishes locally without an API request. A reused ID with different options is rejected. Use a new ID for new work; retrying an existing ID resumes its original snapshot.

Durability and cleanup

Job snapshots and IDs are atomically persisted in project.inlang/.paraglide-batches/. Keep this directory on persistent storage and exclude it from source control: it contains message text and archived model outputs. API keys are never stored in job records. Locks serialize job reconciliation and catalog writes across processes on the same host. Source or target edits made during the batch are preserved and reported as conflicts. Per-locale merges can be replayed after an interrupted collection.

Lost batch creation responses are reconciled through OpenAI batch metadata and the input file ID. An uncertain submission is never automatically repeated, which avoids duplicate paid batches. If reconciliation finds no matching batch, the job stays pending and reports lastError; inspect it in OpenAI before deciding to submit replacement work. OpenAI validates model availability asynchronously; unsupported models are reported through batch errors.

There is no “close completed batch” operation. Once results are safely archived and applied, the service deletes the remote input, output, and error files. Cleanup failures remain resumable. Both uploaded and generated files have a 30-day expiration as a fallback; collect before they expire. cancel_translation_job records cancellation before sending it to OpenAI. Cancellation can take up to 10 minutes; keep collecting until terminal and cleanedUp: true. Successful partial results from cancelled or expired batches are validated and applied too.

For unattended collection, run this command periodically through your own scheduler:

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

It reconciles every unfinished local job once, prints JSON summaries, and exits. No timers or workers remain attached to MCP sessions. It returns a nonzero exit code for collection errors or rejected translations.

Tools

Tool	Purpose
project_info	Locales, source, counts and startup style brief
list_message_keys	Flat keys filtered by prefix/status; cursor pagination
get_messages	Message values by key or prefix
search_messages	Search text and key substrings
save_translations	Validated corrections to existing keys
start_translation_job	Submit a durable OpenAI Batch job
get_translation_job	Reconcile, collect and clean up a job
list_translation_jobs	Local job summaries, cursor pagination
cancel_translation_job	Request cancellation, retaining partial results

The old agent translation loops, workflow prompts, duplicate resources and destructive catalog/locale management tools have been removed from the MCP surface. Existing TranslationService library helpers remain available for callers that need them. MCP saves no longer expose validation bypasses or arbitrary new-key creation.

Stateless HTTP

The CLI uses SDK v2 serveStdio; the library also exports a web-standard HTTP handler:

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.

The handler creates a fresh MCP server for each request and supports the 2026-07-28 protocol without initialization or session IDs. Legacy clients are served statelessly through SDK compatibility. Deployments must mount authentication and Host/Origin checks ahead of fetch as described in the SDK HTTP guide. The filesystem store supports one host, or a persistent single-writer deployment; multi-host replicas need a shared transactional job/catalog store and distributed locking.

See COMPATIBILITY.md for supported message formats and DEVELOPMENT.md for architecture and tests. The optional agent skill teaches the batch workflow.

License

MIT