Shipi18n

Shipi18n

Catch broken translations before you ship them. Shipi18n is an open-source check for locale files: it fails CI when a translation — from a human, a TMS or an AI agent — drops or breaks a placeholder, plural or key, and shows the exact fix.

• Detects: dropped or renamed placeholders ({name}, {{count}}, %{name}, %s, %1$s, %@), plurals whose separator was lost or that miss a form the language needs (Polish few/many, Arabic two — in ICU, i18next keys, Rails, Android and .xcstrings), invalid ICU MessageFormat, missing and orphaned keys, a key written twice in one JSON object, empty and untranslated strings.
• Formats: JSON (i18next, vue-i18n, next-intl, flat or nested), YAML including Rails, Flutter ARB, Apple .xcstrings, Android strings.xml, gettext .po, XLIFF.
• Uploads anything? No. The check runs offline, on your machine or CI runner.
• Needs a key or account? No. Only the optional --semantic review and translate use your own LLM key.

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

Exit 0 clean, 1 findings (each with a one-line fix), 2 usage error. Output as text, JSON, SARIF (GitHub PR annotations) or JUnit.

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

Choose your task

What it doesn't do

• It is not a hosted service or a TMS: no account, dashboard or pricing. (An earlier hosted translation API was retired.)
• It is not a library you import from Python or Ruby; it is a CLI you run from any CI.
• Without --semantic it checks structure, not whether a translation reads well.

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 — 95 repos scanned · 23 ship a verified broken string · 402 strings verified by hand · fixed upstream in 8 repos.

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/cli 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

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/cli 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.