# Shipi18n

[![CI](https://github.com/Shipi18n/shipi18n/actions/workflows/ci.yml/badge.svg)](https://github.com/Shipi18n/shipi18n/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@shipi18n/core?label=%40shipi18n%2Fcore)](https://www.npmjs.com/package/@shipi18n/core)
[![MCP](https://img.shields.io/npm/v/@shipi18n/mcp?label=%40shipi18n%2Fmcp)](https://www.npmjs.com/package/@shipi18n/mcp)
[![downloads](https://img.shields.io/npm/dm/@shipi18n/cli?label=downloads)](https://www.npmjs.com/package/@shipi18n/cli)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![Smithery](https://img.shields.io/badge/Smithery-96%2F100-6b46c1)](https://smithery.ai/servers/ogreenowow/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,
  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.

```bash
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.

![shipi18n check finding a dropped placeholder, then an LLM catching a translation that says "will save" where the English says "delete"](docs/check-demo.gif)

*A real run, not a mockup — [`docs/check-demo.tape`](docs/check-demo.tape) reproduces it.*

### Choose your task

| I want to… | Use |
| --- | --- |
| check locale files locally or in any CI | `npx @shipi18n/cli check ./locales -s en` |
| annotate GitHub pull requests | [`Shipi18n/shipi18n-github-action@v3`](https://github.com/Shipi18n/shipi18n-github-action) ([setup](https://shipi18n.com/docs/github-action/setup)) |
| run it without Node | Docker `ghcr.io/shipi18n/cli`, or the [pre-commit hook](packages/cli/README.md#pre-commit) |
| run it without npm | the single file `shipi18n.mjs` from [GitHub releases](https://github.com/Shipi18n/shipi18n/releases), with a SHA-256 and a build-provenance attestation |
| use it from a Python, Ruby, Go or Java project | the same CLI via Docker, pre-commit or the single file. There is no Python or Ruby package to import |
| have my AI coding agent check its own translations | `npx @shipi18n/cli init --agents`, or the MCP server [`@shipi18n/mcp`](packages/mcp) |
| check meaning, not only structure | `check --semantic` with your own Anthropic or OpenAI key |
| translate (optional) | `shipi18n translate` with your own key |

### 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):

```text
$ 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.

| Repo | What happened |
|---|---|
| Solidus | 13 dropped `%{…}` interpolations in pt-BR — [PR merged the same day](https://github.com/solidusio/solidus/pull/6626), three core approvals |
| Plane | Czech toasts lost `{templateName}`/`{templateType}` — [PR merged in 3 hours](https://github.com/makeplane/plane/pull/9848) |
| nocodb | [our issue](https://github.com/nocodb/nocodb/issues/14573) → [maintainer PR sweeping all 39 locales](https://github.com/nocodb/nocodb/pull/14581); later [182 plurals in 13 locales](https://github.com/nocodb/nocodb/issues/14717) whose `\|` machine translation had turned into `<unk>`, fixed [the same day](https://github.com/nocodb/nocodb/pull/14718) |
| Excalidraw | [our issue](https://github.com/excalidraw/excalidraw/issues/12097) → [contributor fix + a placeholder-parity test suite](https://github.com/excalidraw/excalidraw/pull/12109) |
| Hoppscotch | the `af` run above — [PR merged](https://github.com/hoppscotch/hoppscotch/pull/6648), 7 strings |
| 24pullrequests | 20 dropped interpolations fixed in two PRs, then [an interpolation check added to their own test suite](https://github.com/24pullrequests/24pullrequests/pull/5086) |
| devise_invitable | `%{email)` typo fixed, then [the check added to their CI](https://github.com/scambra/devise_invitable/pull/928) |

Every false positive the scan exposed in our own checker became a fixture in [`evals/placeholders/corpus.jsonl`](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:

```bash
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`](https://github.com/Shipi18n/shipi18n/commit/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/`](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`](packages/core) | The engine: translation checks, the semantic judge, placeholder validation — plus provider-agnostic, structure-preserving translation with incremental mode. |
| [`@shipi18n/cli`](packages/cli) | `shipi18n check ./locales` for CI, `--semantic` for meaning, `lock` to protect hand-edits, `translate` when you need it. |
| [`@shipi18n/mcp`](packages/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`](packages/vite-plugin) | Vite plugin that translates locale files at build time with your own LLM key, with caching. |
| [`shipi18n-github-action`](https://github.com/Shipi18n/shipi18n-github-action) | Check locale files on every PR (no key, SARIF annotations); optional BYO-key retranslate. |

## 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](https://github.com/Shipi18n/shipi18n-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](packages/cli/README.md#no-node-run-the-check-in-any-ci-with-docker).
- **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:

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

**Claude Desktop / any MCP client** — paste the config:

```jsonc
// 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:

```bash
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:

```bash
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](packages/cli/README.md).

## 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.

```bash
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):

```js
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/`](./examples) — [react](./examples/react) (Vite + react-i18next),
[nextjs](./examples/nextjs) (App Router), [vue](./examples/vue) (vue-i18n), and
[nodejs](./examples/nodejs) (`@shipi18n/core`). `cd` into one, install, and run its check/translate scripts.

## Development

This is a pnpm + turbo monorepo.

```bash
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](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](LICENSE) © Shipi18n. See [NOTICE](NOTICE).