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](https://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

`@shipi