@shipi18n/cli 2.0.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @shipi18n/cli
 
+## 2.4.0
+
+- Fix: `check --semantic` explains a `judged 0`. When every translated key has a structural error
+  there is nothing for the judge to look at — correct, but it looked broken. The CLI now says how
+  many keys it skipped and to fix those first.
+- Fix (via core 2.4.0): the missing-SDK error names the install that works for the `npx` path.
+- Note: the npm description on this page was stale until this release — npm only refreshes it on
+  publish, so the registry still led with translation after the project repositioned around QA.
+
+## 2.3.0
+
+- New: `shipi18n lock [path]` — record hand-edited translations in a readable, commit-friendly
+  `.shipi18n/locks.json`. `--keys` globs, `--lang`, `--relock`.
+- New: `check` reports `manual-translation-clobbered` and `manual-translation-stale` (warnings only —
+  locks protect human work and must never fail a pipeline). `--no-locks` disables.
+- Fix: `--no-locks` did nothing. Commander pairs it with `--locks <file>`, so the negation arrives as
+  `locks: false`; the code only checked `noLocks`.
+
+## 2.2.0
+
+- New: `shipi18n check --semantic` — BYO-key LLM-judge pass on top of the structural check.
+  - Advisory by default: semantic findings are warnings and never fail CI unless you opt in with
+    `--semantic-fail`.
+  - Structural-first: keys that already have structural errors are not sent to the judge.
+  - Incremental: verdicts are cached (`--semantic-cache`, default `.shipi18n/semantic-cache.json`);
+    unchanged strings cost zero model calls on re-runs.
+  - `--glossary <file>` enforces do-not-translate and locked terms deterministically (no LLM) and
+    feeds the glossary to the judge as context.
+  - New flags: `-p/--provider`, `--api-key`, `--semantic-model`, `--semantic-passes`.
+  - Semantic findings flow through all reporters; SARIF remains schema-valid.
+
+## 2.1.0
+
+- New command: `shipi18n check [path]` — validate translated locale files against the source
+  language in CI. No LLM, no API key, no network.
+  - Auto-detects flat (`locales/en.json`) and nested (`locales/en/<ns>.json`) JSON trees, Flutter
+    ARB directories and Apple `.xcstrings` catalogs.
+  - Reporters: `human`, `json`, `sarif` (GitHub code-scanning / PR annotations) and `junit`.
+  - `--fail-on error|warning|none`, `--min-coverage <pct>`, `--ignore-keys <globs>`,
+    `--output <file>`. Exit codes: 0 pass, 1 findings, 2 usage error.
+  - Errors can fail CI; warnings never do by default.
+
 ## 2.0.0
 
 **Breaking — bring-your-own-LLM.** Rebuilt on `@shipi18n/core`; no Shipi18n account or hosted API.

package/README.md

@@ -1,15 +1,42 @@
 # @shipi18n/cli
 
-Open-source, **bring-your-own-LLM** i18n translation CLI. Translate your locale files with your own
-OpenAI or Anthropic key — no Shipi18n account, no hosted API.
+**Catch broken translations before you ship them** — and translate with your own LLM key when you
+want to. Open-source, no account, no hosted API.
+
+## Quickstart — check, no API key
 
 ```bash
-npm i -g @shipi18n/cli @anthropic-ai/sdk   # or add `openai` for the OpenAI provider
+npx @shipi18n/cli check ./locales -s en
+```
+
+Reports missing and orphaned keys, dropped placeholders, collapsed plurals, empty values,
+untranslated copy and per-language coverage. Deterministic and offline — no LLM, no key, nothing
+leaves your machine. Exit code `1` when there are errors, so it works as a CI gate as-is.
+
+Then, for the errors structure cannot see, bring a key. The judge needs a provider SDK next to the
+CLI, so install both:
+
+```bash
+npm i -D @shipi18n/cli @anthropic-ai/sdk   # or `openai`
+export ANTHROPIC_API_KEY=sk-ant-...
+npx shipi18n check ./locales -s en --semantic
 ```
 
-## Quickstart
+An LLM reads each source/translation pair and reports mistranslations, omissions and additions —
+advisory by default, so it never fails your build unless you ask it to.
+
+> **Note.** `--semantic` only judges keys that pass the structural checks, so if a tree is full of
+> missing keys and dropped placeholders you will see `judged 0` and no model calls. That is by
+> design — fix the structural errors first, then re-run for meaning.
+
+**Measured** on a 228-pair corpus committed before the judge was written: **100% of planted errors
+caught, 7.1% false positives.** Full harness in the repo under `evals/semantic/` — run it against
+your own model.
+
+## Translating
 
 ```bash
+npm i -g @shipi18n/cli @anthropic-ai/sdk   # or add `openai` for the OpenAI provider
 export ANTHROPIC_API_KEY=sk-ant-...
 shipi18n translate en.json --target es,fr,de
 ```
@@ -45,6 +72,133 @@ shipi18n translate en.json -p openai -t de --api-key $OPENAI_API_KEY
 shipi18n translate en.json -t es --incremental
 ```
 
+## Check — validate translations in CI (no LLM, no key)
+
+`shipi18n check` is a deterministic QA gate for translated locale files. It works on output from
+**any** translator — this CLI, another tool, an agent, or a human — and needs no API key, so it can
+run on every push.
+
+```bash
+npx @shipi18n/cli check ./locales --source en
+```
+
+It detects both common layouts (`locales/en.json` and `locales/en/<ns>.json`), plus Flutter ARB
+directories and Apple String Catalogs (`shipi18n check Localizable.xcstrings`).
+
+**What it catches:** missing and orphaned keys · dropped or invented placeholders (`{{name}}`,
+`{count}`, `%s`, `%1$s`, `%@`, `%lld`, `$t(...)`, `%{name}`, HTML tags) · collapsed vue-i18n pipe
+plurals · empty values · untranslated copy · stale `.xcstrings` states.
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `-s, --source <lang>` | `en` | Source language |
+| `-r, --reporter <name>` | `human` | `human` \| `json` \| `sarif` \| `junit` |
+| `-o, --output <file>` | stdout | Write the report to a file |
+| `--ignore-keys <globs>` | — | Silence keys: `'*.copyright,home:mcp.badge'` |
+| `--fail-on <level>` | `error` | `error` \| `warning` \| `none` |
+| `--min-coverage <pct>` | — | Fail any language below this coverage |
+
+Exit codes: `0` pass, `1` findings at the fail level, `2` usage error. Errors may fail CI; warnings
+never do by default — a warning that blocks PRs gets the tool uninstalled.
+
+### GitHub Actions with PR annotations
+
+```yaml
+- name: Check translations
+  run: npx @shipi18n/cli check ./locales -s en --reporter sarif --output i18n.sarif
+
+- name: Upload findings
+  if: always()
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: i18n.sarif
+```
+
+## Semantic QA — `--semantic` (the judge)
+
+The structural check cannot see a translation that is *fluent but wrong*. `--semantic` adds an
+LLM-as-judge pass with your own key:
+
+```bash
+npx @shipi18n/cli check ./locales -s en --semantic          # advisory: warnings only
+npx @shipi18n/cli check ./locales -s en --semantic --glossary glossary.json
+```
+
+**Honest limitations, up front:** the judge is probabilistic. Every key is judged across 3 passes
+and flagged only on a majority vote, unparseable passes are discarded, and semantic findings are
+**warnings by default** — they never fail CI unless you opt in with `--semantic-fail`. It augments
+review; it does not replace it. You pay your provider for the tokens; the verdict cache
+(`.shipi18n/semantic-cache.json`, safe to commit) makes unchanged re-runs free, and keys that
+already failed the structural check are never sent to the judge.
+
+What it flags: `semantic-mistranslation` (says something different), `semantic-omission` (meaning
+dropped), `semantic-addition` (meaning invented).
+
+**Measured** (committed 228-pair corpus, thresholds fixed before the judge was built, default judge
+`claude-haiku-4-5`, 3 passes). Two independent runs, 2026-08-16 and 2026-08-17:
+
+| | 2026-08-16 | 2026-08-17 |
+| --- | --- | --- |
+| planted errors caught | 54/54 (100%) | 54/54 (100%) |
+| per-category recall | 100% | 100% |
+| label accuracy | 100% | 53/54 (98.1%) |
+| false positives on clean pairs | 12/168 (7.1%) | 12/168 (7.1%) |
+| glossary violations | 6/6, 0 false | 6/6, 0 false |
+| cost | ~62k tokens / 141s | ~59k tokens / 156s, 48 calls |
+
+The judge is a model, so treat these as a range, not a constant — label accuracy moved between runs
+while catch and false-positive rates held. On a real 478-pair production tree it flagged 3.6% of keys;
+the warm-cache rerun made **zero** model calls. Full harness: `evals/semantic/` in the repo — run it
+against your own model and publish what you get.
+
+### Glossary (deterministic — no LLM)
+
+```json
+{
+  "Shipi18n": { "dnt": true },
+  "dashboard": { "es": "panel", "de": "Dashboard", "ja": "ダッシュボード" }
+}
+```
+
+`"dnt"` terms must survive verbatim; language entries are required translations. Violations are
+`glossary-violation` **errors**, caught by string matching at zero cost, and the glossary is also
+given to the judge as context.
+
+## Protect hand-edited translations — `shipi18n lock`
+
+The oldest complaint about machine translation: you fix a string by hand, the tool runs again, and
+your fix is gone. Lock the translations a human has blessed, and `check` tells you when that happens.
+
+```bash
+# bless everything currently in the tree
+npx @shipi18n/cli lock ./locales
+
+# or just the strings you actually hand-edited
+npx @shipi18n/cli lock ./locales --keys 'legal.*,checkout.cta'
+npx @shipi18n/cli lock ./locales --lang de,ja      # narrow to some languages
+```
+
+This writes `.shipi18n/locks.json` — **commit it**, it is the record of which translations a person
+reviewed. It stores only hashes, never your strings.
+
+Afterwards `check` reports two new findings:
+
+| Finding | Meaning |
+| --- | --- |
+| `manual-translation-clobbered` | the locked translation's text changed — someone re-translated over a human edit |
+| `manual-translation-stale` | the **source** changed underneath a locked translation, so the human edit may no longer be right |
+
+Both are **warnings, never errors**: this feature exists to protect people's work, not to block their
+pipeline. A lock that failed CI would just get deleted. Use `--fail-on warning` if you disagree, or
+`--no-locks` to ignore the lock file entirely.
+
+```bash
+# accept the current state as the new blessed baseline
+npx @shipi18n/cli lock ./locales --relock
+```
+
+A missing or corrupt lock file is a cold start, not a crash.
+
 ## Bring your own LLM
 
 Set `ANTHROPIC_API_KEY` (default provider) or use `-p openai` with `OPENAI_API_KEY`. Your keys, your

package/bin/shipi18n.js

@@ -5,6 +5,8 @@ import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { translateCommand } from '../src/commands/translate.js'
+import { checkCommand } from '../src/commands/check.js'
+import { lockCommand } from '../src/commands/lock.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'))
@@ -21,6 +23,8 @@ ${chalk.cyan('Examples:')}
   $ export ANTHROPIC_API_KEY=sk-ant-...
   $ shipi18n translate en.json --target es,fr,de
   $ shipi18n translate en.json -p openai --target ja --incremental
+  $ shipi18n check ./locales --source en --min-coverage 95
+  $ shipi18n lock ./locales --keys 'legal.*'   # protect hand-edited strings
 
 ${chalk.cyan('Bring your own LLM:')}
   Set ${chalk.yellow('ANTHROPIC_API_KEY')} (default) or use ${chalk.yellow('-p openai')} with ${chalk.yellow('OPENAI_API_KEY')}.
@@ -31,5 +35,7 @@ ${chalk.gray('https://github.com/Shipi18n/shipi18n')}
   )
 
 translateCommand(program)
+checkCommand(program)
+lockCommand(program)
 program.parse(process.argv)
 if (!process.argv.slice(2).length) program.outputHelp()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipi18n/cli",
-  "version": "2.0.0",
-  "description": "Open-source, bring-your-own-LLM i18n translation CLI. Translate locale files with your own OpenAI/Anthropic key.",
+  "version": "2.4.0",
+  "description": "Catch broken translations before you ship: dropped placeholders, missing keys, collapsed plurals and — with your own LLM key — mistranslations the structure checks cannot see. CI-ready (SARIF, JUnit, exit codes). Translates too.",
   "type": "module",
   "bin": {
     "shipi18n": "./bin/shipi18n.js"
@@ -9,6 +9,7 @@
   "files": [
     "bin",
     "src",
+    "!src/__tests__",
     "LICENSE",
     "NOTICE",
     "README.md",
@@ -18,6 +19,11 @@
     "access": "public"
   },
   "keywords": [
+    "sarif",
+    "ci",
+    "lint",
+    "translation-quality",
+    "i18n-qa",
     "i18n",
     "cli",
     "translation",
@@ -38,7 +44,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "ora": "^8.0.1",
-    "@shipi18n/core": "^2.0.0"
+    "@shipi18n/core": "^2.4.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.30.0",
@@ -53,6 +59,8 @@
     }
   },
   "devDependencies": {
+    "ajv": "^8.20.0",
+    "fast-xml-parser": "^5.10.1",
     "jest": "^29.7.0"
   },
   "scripts": {

package/src/commands/check.js

@@ -0,0 +1,170 @@
+/**
+ * `shipi18n check` — structural QA for locale files, designed to live in CI.
+ *
+ * Deterministic and offline: no LLM, no API key, no network. Reports the
+ * failure modes machine translation actually produces — dropped placeholders,
+ * collapsed plurals, missing keys, untranslated copy — and exits non-zero so a
+ * pipeline can gate on it.
+ *
+ * Formats: plain JSON locale trees (flat `locales/<lang>.json` or nested
+ * `locales/<lang>/<ns>.json`), Flutter ARB directories, and Apple String
+ * Catalogs (`.xcstrings`). Reporters: human, json, sarif, junit.
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
+import { resolve, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import chalk from 'chalk'
+import {
+  runCheck,
+  runSemantic,
+  discoverLayout,
+  compileIgnores,
+  statsFrom,
+  aggregateLanguage,
+  SEP,
+} from '@shipi18n/core'
+import { REPORTERS } from '../reporters.js'
+import { locksFor, DEFAULT_LOCKS_PATH } from './lock.js'
+
+const pkg = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf8')
+)
+
+/* ------------------------------------------------------------------ engine */
+
+// Layout discovery and tree walking live in @shipi18n/core so the CLI and the
+// MCP validator tools cannot drift apart. Re-exported here because the CLI's
+// tests and semantic pass are written against these names.
+export { runCheck, runSemantic, discoverLayout, compileIgnores, statsFrom, aggregateLanguage, SEP }
+
+/* ---------------------------------------------------------------- verdict */
+
+/** Decide the exit code from findings and flags. Reporters never influence this. */
+export function verdict(result, { failOn = 'error', minCoverage } = {}) {
+  const failures = []
+  if (failOn === 'error' && result.totals.errors > 0) failures.push(`${result.totals.errors} error(s)`)
+  if (failOn === 'warning' && result.totals.errors + result.totals.warnings > 0)
+    failures.push(`${result.totals.errors} error(s), ${result.totals.warnings} warning(s)`)
+  if (minCoverage != null) {
+    for (const l of result.languages) {
+      if (l.stats.coverage * 100 < minCoverage)
+        failures.push(`${l.lang} coverage ${(l.stats.coverage * 100).toFixed(1)}% < ${minCoverage}%`)
+    }
+  }
+  return { ok: failures.length === 0, failures }
+}
+
+/* ---------------------------------------------------------------- command */
+
+export function checkCommand(program) {
+  program
+    .command('check [input]')
+    .description('Validate translated locale files against the source language (no LLM, no key)')
+    .option('-s, --source <language>', 'Source language', 'en')
+    .option('-r, --reporter <name>', 'Output format: human | json | sarif | junit', 'human')
+    .option('-o, --output <file>', 'Write the report to a file instead of stdout')
+    .option('--json', 'Shorthand for --reporter json')
+    .option('--ignore-keys <patterns>', "Comma-separated '*' globs of keys to silence (path or ns:path)")
+    .option('--fail-on <level>', 'Exit non-zero on: error | warning | none', 'error')
+    .option('--min-coverage <pct>', 'Fail any language below this coverage percentage', parseFloat)
+    .option('--glossary <file>', 'Glossary JSON: DNT terms + locked per-language translations (deterministic)')
+    .option('--semantic', 'Add the LLM-as-judge pass (BYO key; advisory warnings by default)')
+    .option('--semantic-fail', 'Escalate semantic findings to errors (opt-in)')
+    .option('-p, --provider <name>', 'LLM provider for --semantic: anthropic | openai', 'anthropic')
+    .option('--api-key <key>', 'LLM API key for --semantic (else provider env var)')
+    .option('--semantic-model <model>', 'Judge model override')
+    .option('--semantic-passes <n>', 'Judge passes for the majority vote', (v) => parseInt(v, 10), 3)
+    .option('--semantic-cache <file>', 'Verdict cache path', '.shipi18n/semantic-cache.json')
+    .option('--locks <file>', 'Manual-translation lock file', DEFAULT_LOCKS_PATH)
+    .option('--no-locks', 'Ignore manual-translation locks')
+    .action(async (input = './locales', opts) => {
+      let glossary
+      if (opts.glossary) {
+        try {
+          glossary = JSON.parse(readFileSync(opts.glossary, 'utf8'))
+        } catch (err) {
+          console.error(chalk.red(`Error: cannot read glossary ${opts.glossary}: ${err.message}`))
+          process.exitCode = 2
+          return
+        }
+      }
+
+      let result
+      try {
+        result = runCheck({
+          input,
+          source: opts.source,
+          ignoreKeys: opts.ignoreKeys,
+          glossary,
+          locks: locksFor(opts),
+        })
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`))
+        process.exitCode = 2
+        return
+      }
+
+      if (opts.semantic) {
+        const cachePath = resolve(opts.semanticCache)
+        let cache = {}
+        if (existsSync(cachePath)) {
+          try {
+            cache = JSON.parse(readFileSync(cachePath, 'utf8'))
+          } catch {
+            cache = {} // a corrupt cache is just a cold cache
+          }
+        }
+        try {
+          const judge = await runSemantic(result, {
+            provider: opts.provider,
+            apiKey: opts.apiKey,
+            model: opts.semanticModel,
+            passes: opts.semanticPasses,
+            glossary,
+            cache,
+            fail: Boolean(opts.semanticFail),
+          })
+          mkdirSync(dirname(cachePath), { recursive: true })
+          writeFileSync(cachePath, JSON.stringify(cache, null, 2) + '\n')
+          console.error(
+            chalk.gray(
+              `semantic: judged ${judge.judged} (${judge.cached} cached), flagged ${judge.flagged}, ` +
+                `${judge.calls} model call(s), ${judge.parseFailures} discarded pass(es)`
+            )
+          )
+          // "judged 0" on a badly broken tree is correct but reads as a broken
+          // feature: the judge skips keys that already carry a structural error.
+          if (judge.judged === 0 && judge.excluded > 0) {
+            console.error(
+              chalk.yellow(
+                `note: nothing was judged — all ${judge.excluded} translated key(s) have structural ` +
+                  `errors, which the semantic pass skips. Fix those first, then re-run with --semantic.`
+              )
+            )
+          }
+        } catch (err) {
+          console.error(chalk.red(`Semantic pass failed: ${err.message}`))
+          process.exitCode = 2
+          return
+        }
+      }
+
+      const verdictResult = verdict(result, { failOn: opts.failOn, minCoverage: opts.minCoverage })
+
+      const name = opts.json ? 'json' : opts.reporter
+      const reporter = REPORTERS[name]
+      if (!reporter) {
+        console.error(chalk.red(`Error: unknown reporter '${name}' (human | json | sarif | junit)`))
+        process.exitCode = 2
+        return
+      }
+      const report = reporter(result, verdictResult, { toolVersion: pkg.version })
+      if (opts.output) {
+        writeFileSync(opts.output, report.endsWith('\n') ? report : report + '\n')
+        if (name !== 'human') console.error(chalk.gray(`report written to ${opts.output}`))
+      } else {
+        console.log(report)
+      }
+      if (!verdictResult.ok) process.exitCode = 1
+    })
+}

package/src/commands/lock.js

@@ -0,0 +1,131 @@
+/**
+ * `shipi18n lock` — mark translations as hand-edited so `check` can tell you
+ * when something overwrites them, or when their source moves underneath.
+ *
+ * Writes `.shipi18n/locks.json` (safe to commit — it is the record of which
+ * translations a human has blessed).
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import chalk from 'chalk'
+import {
+  runCheck,
+  discoverLayout,
+  compileIgnores,
+  lockId,
+  lockEntry,
+  emptyLocks,
+  normalizeLocks,
+  flatten,
+} from '@shipi18n/core'
+
+export const DEFAULT_LOCKS_PATH = '.shipi18n/locks.json'
+
+/** Tolerant read — a missing or corrupt file is simply "no locks yet". */
+export function readLocks(path) {
+  if (!existsSync(path)) return emptyLocks()
+  try {
+    return normalizeLocks(JSON.parse(readFileSync(path, 'utf8')))
+  } catch {
+    return emptyLocks()
+  }
+}
+
+export function writeLocks(path, locks) {
+  mkdirSync(dirname(resolve(path)), { recursive: true })
+  writeFileSync(resolve(path), JSON.stringify(locks, null, 2) + '\n')
+}
+
+/**
+ * Build the lock set for a tree. Only pairs that actually exist in both source
+ * and target are lockable — you cannot bless a translation that isn't there.
+ */
+export function buildLocks({ input, source = 'en', keys, existing = emptyLocks(), langs }) {
+  const isSelected = compileIgnores(keys) // same glob syntax as --ignore-keys
+  const selectAll = !keys
+  const layout = discoverLayout(input, source)
+  const locked = { ...existing.locked }
+  let added = 0
+
+  const sourceData = {}
+  for (const [ns, file] of Object.entries(layout.source)) {
+    sourceData[ns] = JSON.parse(readFileSync(file, 'utf8'))
+  }
+
+  for (const { lang, files } of layout.targets) {
+    if (langs && !langs.includes(lang)) continue
+    for (const [ns, srcObj] of Object.entries(sourceData)) {
+      const file = files[ns]
+      if (!file || !existsSync(file)) continue
+      let targetObj
+      try {
+        targetObj = JSON.parse(readFileSync(file, 'utf8'))
+      } catch {
+        continue // an unparseable file has nothing lockable in it
+      }
+      const src = flatten(srcObj)
+      const tgt = flatten(targetObj)
+      for (const [path, value] of Object.entries(src)) {
+        if (typeof value !== 'string' || typeof tgt[path] !== 'string') continue
+        if (!selectAll && !isSelected(ns, path)) continue
+        const id = lockId(lang, ns, path)
+        if (!(id in locked)) added++
+        locked[id] = lockEntry(value, tgt[path])
+      }
+    }
+  }
+  return { locks: { ...emptyLocks(), locked }, added, total: Object.keys(locked).length }
+}
+
+export function lockCommand(program) {
+  program
+    .command('lock [input]')
+    .description('Record translations as hand-edited, so check warns when they are overwritten')
+    .option('-s, --source <language>', 'Source language', 'en')
+    .option('-k, --keys <patterns>', "Only lock keys matching these '*' globs (default: all)")
+    .option('-l, --lang <languages>', 'Only lock these languages (comma-separated)')
+    .option('--locks <file>', 'Lock file path', DEFAULT_LOCKS_PATH)
+    .option('--relock', 'Update hashes for keys already locked (accept current state as blessed)')
+    .action((input = './locales', opts) => {
+      try {
+        const path = resolve(opts.locks)
+        const existing = opts.relock ? emptyLocks() : readLocks(path)
+        const langs = opts.lang ? opts.lang.split(',').map((l) => l.trim()) : undefined
+        const { locks, added, total } = buildLocks({
+          input,
+          source: opts.source,
+          keys: opts.keys,
+          existing,
+          langs,
+        })
+        writeLocks(path, locks)
+        console.log(
+          chalk.green(`✓ locked ${added} new translation(s); ${total} total in ${opts.locks}`)
+        )
+        if (!opts.keys) {
+          console.log(
+            chalk.gray('  Tip: --keys narrows this to the strings you actually hand-edited.')
+          )
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`))
+        process.exitCode = 2
+      }
+    })
+}
+
+/**
+ * Used by `check` to load locks unless disabled.
+ *
+ * Commander pairs `--no-locks` with `--locks <file>`, so the negation arrives as
+ * `opts.locks === false` rather than `opts.noLocks` — checking only the latter
+ * made --no-locks silently do nothing (caught by an end-to-end run, not by a
+ * unit test that hand-built the options object).
+ */
+export function locksFor(opts = {}) {
+  if (opts.locks === false || opts.noLocks) return undefined
+  const path = resolve(typeof opts.locks === 'string' ? opts.locks : DEFAULT_LOCKS_PATH)
+  if (!existsSync(path)) return undefined
+  const locks = readLocks(path)
+  return Object.keys(locks.locked).length ? locks : undefined
+}

package/src/reporters.js

@@ -0,0 +1,189 @@
+/**
+ * Output formats for `shipi18n check`.
+ *
+ * Reporters SERIALIZE a result; they never decide it. Exit codes come from
+ * `verdict()` alone, so switching reporter can never change whether CI fails.
+ */
+import chalk from 'chalk'
+
+/* ------------------------------------------------------------------ human */
+
+export function humanReport(result, verdictResult) {
+  const lines = []
+  lines.push('')
+  lines.push(
+    `🔎 shipi18n check — ${result.layout} layout, source '${result.source}', ${result.languages.length} target language(s)`
+  )
+  lines.push('')
+  for (const l of result.languages) {
+    const all = l.namespaces.flatMap((n) => n.findings.map((f) => ({ ...f, ns: n.ns })))
+    const mark = l.stats.errors ? chalk.red('✗') : all.length ? chalk.yellow('⚠') : chalk.green('✓')
+    lines.push(
+      `${mark} ${chalk.bold(l.lang)}  coverage ${(l.stats.coverage * 100).toFixed(1)}%  ${l.stats.errors} error(s), ${l.stats.warnings} warning(s)`
+    )
+    for (const f of all.slice(0, 50)) {
+      const color = f.severity === 'error' ? chalk.red : chalk.yellow
+      const where = result.layout === 'flat' ? f.path : `${f.ns}:${f.path}`
+      lines.push(`    ${color(f.severity)}  ${chalk.cyan(where)}  ${f.type} — ${f.message}`)
+    }
+    if (all.length > 50) lines.push(chalk.gray(`    … and ${all.length - 50} more`))
+  }
+  lines.push('')
+  lines.push(
+    verdictResult.ok
+      ? chalk.green('✓ check passed')
+      : chalk.red(`✗ check failed: ${verdictResult.failures.join('; ')}`)
+  )
+  return lines.join('\n')
+}
+
+/* ------------------------------------------------------------------- json */
+
+export function jsonReport(result, verdictResult) {
+  return JSON.stringify({ ...result, ok: verdictResult.ok, failures: verdictResult.failures }, null, 2)
+}
+
+/* ------------------------------------------------------------------ sarif */
+
+const RULE_META = {
+  'missing-key': 'A key present in the source language is missing from a translation.',
+  'orphan-key': 'A key present in a translation does not exist in the source language.',
+  'placeholder-missing': 'A placeholder from the source string was dropped in the translation.',
+  'placeholder-added': 'The translation contains a placeholder the source does not have.',
+  'plural-forms': 'A pipe-separated plural lost one or more of its forms in translation.',
+  'empty-value': 'The translation of a non-empty source string is empty.',
+  'untranslated': 'The translation is identical to a multi-word source string.',
+  'type-mismatch': 'Source and translation values have different JSON types.',
+  'invalid-json': 'A locale file could not be parsed as JSON.',
+  'missing-file': 'An expected locale file does not exist.',
+  'stale-translation': 'The catalog marks this translation as needing review.',
+  'glossary-violation': 'A do-not-translate or locked glossary term was not respected.',
+  'manual-translation-clobbered': 'A translation locked as hand-edited has been overwritten.',
+  'manual-translation-stale': 'The source changed after this translation was locked by hand.',
+  'semantic-mistranslation': 'LLM judge (majority vote): the translation states something different from the source.',
+  'semantic-omission': 'LLM judge (majority vote): meaningful source content is missing from the translation.',
+  'semantic-addition': 'LLM judge (majority vote): the translation contains claims the source does not make.',
+}
+
+/** SARIF 2.1.0 — one run, one rule per finding type, one result per finding. */
+export function sarifReport(result, _verdictResult, { toolVersion = '0.0.0' } = {}) {
+  const findings = []
+  for (const l of result.languages) {
+    for (const n of l.namespaces) {
+      for (const f of n.findings) findings.push({ lang: l.lang, ns: n.ns, file: n.file, ...f })
+    }
+  }
+  // Deterministic output: stable ordering makes committed SARIF diffable.
+  findings.sort((a, b) =>
+    `${a.file}|${a.path}|${a.type}`.localeCompare(`${b.file}|${b.path}|${b.type}`)
+  )
+
+  const usedTypes = [...new Set(findings.map((f) => f.type))].sort()
+  const ruleIndex = Object.fromEntries(usedTypes.map((t, i) => [t, i]))
+
+  const sarif = {
+    $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'shipi18n-check',
+            informationUri: 'https://github.com/Shipi18n/shipi18n',
+            version: toolVersion,
+            rules: usedTypes.map((t) => ({
+              id: t,
+              shortDescription: { text: RULE_META[t] || t },
+              helpUri: 'https://shipi18n.com/docs/cli/commands',
+            })),
+          },
+        },
+        results: findings.map((f) => ({
+          ruleId: f.type,
+          ruleIndex: ruleIndex[f.type],
+          level: f.severity === 'error' ? 'error' : 'warning',
+          message: { text: `[${f.lang}] ${f.path}: ${f.message}` },
+          locations: [
+            {
+              physicalLocation: {
+                artifactLocation: { uri: (f.file || '').split('\\').join('/') },
+              },
+            },
+          ],
+        })),
+      },
+    ],
+  }
+  return JSON.stringify(sarif, null, 2)
+}
+
+/* ------------------------------------------------------------------ junit */
+
+const xmlEscape = (s) =>
+  String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+
+/**
+ * One <testsuite> per language, one <testcase> per namespace.
+ * Errors become <failure>; warnings go to <system-out> — a warning that fails
+ * CI gets the tool uninstalled.
+ */
+export function junitReport(result) {
+  const suites = []
+  let totalTests = 0
+  let totalFailures = 0
+
+  for (const l of result.languages) {
+    const cases = []
+    let failures = 0
+    for (const n of l.namespaces) {
+      totalTests++
+      const errors = n.findings.filter((f) => f.severity === 'error')
+      const warnings = n.findings.filter((f) => f.severity === 'warning')
+      const body = []
+      if (errors.length) {
+        failures++
+        totalFailures++
+        // Include the offending strings: "dropped {{name}}" is not actionable
+        // without seeing WHICH string dropped it.
+        const detail = errors
+          .map((f) => {
+            const lines = [`${f.path}: ${f.type} — ${f.message}`]
+            if (f.source != null) lines.push(`  source:      ${f.source}`)
+            if (f.translation != null) lines.push(`  translation: ${f.translation}`)
+            return lines.join('\n')
+          })
+          .join('\n')
+        body.push(
+          `      <failure message="${xmlEscape(`${errors.length} error(s) in ${l.lang}/${n.ns}`)}">${xmlEscape(detail)}</failure>`
+        )
+      }
+      if (warnings.length) {
+        const detail = warnings.map((f) => `${f.path}: ${f.type} — ${f.message}`).join('\n')
+        body.push(`      <system-out>${xmlEscape(detail)}</system-out>`)
+      }
+      cases.push(
+        body.length
+          ? `    <testcase classname="${xmlEscape(l.lang)}" name="${xmlEscape(n.ns)}">\n${body.join('\n')}\n    </testcase>`
+          : `    <testcase classname="${xmlEscape(l.lang)}" name="${xmlEscape(n.ns)}"/>`
+      )
+    }
+    suites.push(
+      `  <testsuite name="${xmlEscape(l.lang)}" tests="${l.namespaces.length}" failures="${failures}">\n${cases.join('\n')}\n  </testsuite>`
+    )
+  }
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<testsuites name="shipi18n-check" tests="${totalTests}" failures="${totalFailures}">`,
+    ...suites,
+    '</testsuites>',
+    '',
+  ].join('\n')
+}
+
+export const REPORTERS = { human: humanReport, json: jsonReport, sarif: sarifReport, junit: junitReport }