shipi18n

Shipi18n

Catch broken translations before you ship them. An open-source QA gate for your locale files — and, when you want it, an i18n translation engine that runs on your own LLM key.

Your es.json says Hola where the English says Hello {{name}}. The placeholder is gone, the build is green, and the bug ships. Shipi18n finds that, and it finds the harder kind too: the string that has every placeholder and still says the wrong thing.

A real run, not a mockup — docs/check-demo.tape reproduces it.

npx @shipi18n/cli check ./locales -s en

No API key, no account, no config. Missing keys, dropped placeholders, collapsed plurals, empty values and untranslated copy — as human output, JSON, SARIF (GitHub PR annotations) or JUnit.

Found in the wild. The same command on a real project — Hoppscotch's Afrikaans locale as it was when we ran it (structural rules only; the missing-key noise switched off so the placeholder findings stand out):

$ npx @shipi18n/cli check packages/hoppscotch-common/locales -s en \
    --severity 'missing-key=off,untranslated=off,orphan-key=off'

✗ af  coverage 100.0%  7 error(s), 5 warning(s)
    error  import.file_size_limit_exceeded_warning_multiple_files  placeholder-missing — dropped {sizeLimit}
    error  import.file_size_limit_exceeded_warning_single_file  placeholder-missing — dropped {sizeLimit}
    error  state.connected_to  placeholder-missing — dropped {name}
    warning  state.connected_to  placeholder-added — unexpected {naam}
    error  team.invited_to_team  placeholder-missing — dropped {workspace}
    warning  team.invited_to_team  placeholder-added — unexpected {team}
    …

{naam} is {name} translated; vue-i18n will never substitute it. We scan public repos, verify every finding by hand against the source language, and send the fix upstream. Running tally, one row per repo: shipi18n.com/oss — 64 repos scanned · 21 ship a verified broken string · 119 strings verified by hand · 3 fixed upstream in the first week.

Repo	What happened
Solidus	13 dropped %{…} interpolations in pt-BR — PR merged the same day, three core approvals
Plane	Czech toasts lost {templateName}/{templateType} — PR merged in 3 hours
nocodb	our issue → maintainer PR sweeping all 39 locales
Excalidraw	our issue → contributor fix + a placeholder-parity test suite
Hoppscotch	the af run above — PR open, 7 strings

Every false positive the scan exposed in our own checker became a fixture in evals/placeholders/corpus.jsonl first.

If the check catches something in your project, consider starring the repo — stars are how the next person with a broken es.json finds this.

Then, when you want the meaning checked, bring your own key. The judge needs a provider SDK alongside the CLI:

npm i -D @shipi18n/cli @anthropic-ai/sdk       # or `openai`
export ANTHROPIC_API_KEY=sk-ant-...            # or OPENAI_API_KEY
npx shipi18n check ./locales -s en --semantic

An LLM reads each pair and reports mistranslations, omissions and additions:

⚠ es  coverage 100.0%  0 error(s), 1 warning(s)
    warning  delete  semantic-mistranslation — Translation says 'will save' (guardará)
                     instead of 'will delete' (eliminará/borrará)

Every placeholder is intact and every key is present, so structural checks pass this file. Only reading it catches the bug. Advisory by default — it warns, it does not fail your build.

Measured, not asserted. On a 228-pair corpus committed before the judge was written (60d699b) and with thresholds fixed first: 54/54 planted errors caught (100%) and 12/168 false positives on clean pairs (7.1%), with 6/6 glossary violations found. Reproduced on two independent runs (2026-08-16 and 2026-08-17) using claude-haiku-4-5, 3 passes, ~59k tokens in 156s. Label accuracy moved between runs (100% → 98.1%) — it is a model, so read these as a range, not a constant. The harness is evals/semantic/. Run it against your own model.

Nothing goes through our servers, because there are none. The only network call is from your machine to the provider you chose.

Packages

Package	Description
@shipi18n/core	The engine: translation checks, the semantic judge, placeholder validation — plus provider-agnostic, structure-preserving translation with incremental mode.
@shipi18n/cli	shipi18n check ./locales for CI, --semantic for meaning, lock to protect hand-edits, translate when you need it.
@shipi18n/mcp	MCP server — check, diff and review locale files from Claude Desktop, Cursor, or any MCP client. Validation needs no API key.
vite-plugin-shipi18n	Vite plugin that translates locale files at build time, with caching.
shipi18n-github-action	GitHub Action that keeps translations in sync on push/PR.

Why

Generating translations is a solved problem. Half a dozen good tools will fill your locale files, and an agent will do it for free. Nothing checks the result. Your CI lints your JavaScript, typechecks your types and runs your tests — and then ships a de.json that nobody has read, produced by a model nobody audited.

The checks that do exist are structural: they diff key sets and stop there. That catches the missing key. It does not catch the translation that has every key and every placeholder and still tells your German users the opposite of what you meant.

Shipi18n is that missing gate, in two layers:

• Deterministic, offline, no key. Missing and orphaned keys, dropped or malformed placeholders ({{name}}, {count}, %s, %d, %1$s, $t(...), %{name}, HTML), collapsed plural forms, empty values, untranslated copy, coverage per language.
• Semantic, with your own key. An LLM-as-judge pass over changed keys only, with multi-pass majority voting because single-pass judge scores are unstable. Reports mistranslation, omission and addition. Advisory by default — a QA tool that fails your build gets uninstalled.

Plus the parts that make it usable day to day:

• Formats beyond JSON. YAML (.yaml/.yml), Flutter .arb, Apple .xcstrings, Android strings.xml, gettext .po/.pot, and XLIFF 1.2/2.0 — including %@/%lld specifiers.
• CI-native. Correct exit codes, --fail-on, --min-coverage, SARIF for PR annotations, JUnit.
• Adopts on a messy catalog. --baseline accepts today's backlog and fails only on new findings (the Stylelint/RuboCop pattern); --severity tunes or silences any rule (error|warning|info|off).
• Runs anywhere, Node or not. GitHub Action, a pre-commit hook, or the Docker image ghcr.io/shipi18n/cli for GitLab / Bitbucket / Jenkins / local — no Node toolchain required. See the CLI README.
• WordPress .po ↔ JED sync. shipi18n wp-sync catches JS translation JSON that has drifted from the .po because nobody re-ran wp i18n make-json — a silent bug no other tool checks.
• Privacy pre-flight. Before --semantic sends anything to an LLM, a scan withholds any string carrying a secret or PII (keys, cards, emails); --detect-secrets runs it standalone with no LLM.
• Hand-edits are protected. shipi18n lock records the translations a human blessed and warns when anything overwrites them, or when the source moves underneath them.
• Keyless from your editor. The MCP server's validators call no model at all.
• It also translates. Provider-agnostic, structure-preserving, incremental — Anthropic and OpenAI in the box, and any object with a complete(prompt) method is a valid adapter.

Check from your editor — no API key

@shipi18n/mcp brings the checks to any MCP client. The validation tools call no model, so they need no key at all.

Claude Code — one line:

claude mcp add shipi18n -- npx -y @shipi18n/mcp

Claude Desktop / any MCP client — paste the config:

// claude_desktop_config.json
{
  "mcpServers": {
    "shipi18n": { "command": "npx", "args": ["-y", "@shipi18n/mcp"] }
  }
}

"Check ./locales against English and tell me what's broken in Spanish."

review_locales goes further without needing a key either: it hands your agent the translation pairs and the review criteria, and your agent reasons about meaning with the model it already runs.

Check in CI — no key needed

The checks work on translations from any source — a TMS, another tool, an agent, a human. Run it on every push:

npx @shipi18n/cli check ./locales -s en

Missing keys, dropped placeholders, collapsed plurals, empty values and untranslated copy — reported as human output, JSON, SARIF (GitHub PR annotations) or JUnit. Works on plain JSON trees, YAML, Flutter .arb, Apple .xcstrings, Android strings.xml, gettext .po/.pot and XLIFF (1.2/2.0). Deterministic and offline: no LLM, no API key.

Protect hand-edited translations

Fix a string by hand, lock it, and check warns you if anything ever overwrites it — or if the English moves underneath it:

npx @shipi18n/cli lock ./locales --keys 'legal.*'

.shipi18n/locks.json stores hashes only, is safe to commit, and these findings are warnings — protecting human work must never block a pipeline. Details in the CLI README.

It also translates

Checking works on translations from anywhere, but if you want Shipi18n to produce them too, it does — with your key, your model, and nothing in between.

npm i -D @shipi18n/cli @anthropic-ai/sdk       # or `openai`
export ANTHROPIC_API_KEY=sk-ant-...            # or OPENAI_API_KEY
npx shipi18n translate locales/en.json -t es,fr,de

✔ es → locales/es.json (2 translated, 0 reused)

Or from Node (same SDK requirement):

import { translateJSON } from '@shipi18n/core'

const { result, stats } = await translateJSON({
  content: { greeting: 'Hello {{name}}' },
  from: 'en',
  to: 'es',
  provider: 'anthropic',        // 'anthropic' | 'openai' | custom { complete } adapter
})
// result → { greeting: 'Hola {{name}}' }

Structure-preserving, placeholder-safe and incremental — only new or changed keys are sent to the model. Then check the result with the same tool.

Examples

Runnable projects in examples/ — react (Vite + react-i18next), nextjs (App Router), vue (vue-i18n), and nodejs (@shipi18n/core). cd into one, install, and run its check/translate scripts.

Development

This is a pnpm + turbo monorepo.

pnpm install
pnpm test          # all packages
pnpm --filter @shipi18n/core test

Changesets manage versioning: pnpm changeset to add one.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. pnpm install && pnpm test runs 105 tests against a mock adapter, so you need no API key to work on this.

License

Apache-2.0 © Shipi18n. See NOTICE.