@shipi18n/cli 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @shipi18n/cli
 
+## 2.5.0
+
+- New: `--base-url <url>` on `translate` and `check` — run against any OpenAI-compatible endpoint
+  with `-p openai`: Ollama (`http://localhost:11434/v1`, no API key at all), Gemini's compatibility
+  endpoint, Groq, LM Studio, vLLM. Makes the API key optional; the judge's published accuracy was
+  measured on `claude-haiku-4-5`, so run `evals/semantic/run.mjs` before trusting a different judge.
+- Guard: `--base-url` without `-p openai` is an explicit error rather than a silent provider switch.
+
+## 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

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
 ```
 
-## Quickstart
+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
+```
+
+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
 ```
@@ -29,6 +56,7 @@ Options:
   -p, --provider <name>    LLM provider: anthropic (default) or openai
       --api-key <key>      LLM API key (else ANTHROPIC_API_KEY / OPENAI_API_KEY env)
       --model <model>      Override the provider's default model
+      --base-url <url>     OpenAI-compatible endpoint (Ollama, Gemini compat, ...); needs -p openai
   -i, --incremental        Reuse existing output files; only translate new/missing keys
 ```
 
@@ -43,6 +71,13 @@ shipi18n translate en.json -p openai -t de --api-key $OPENAI_API_KEY
 
 # Incremental — only translate keys not already in the target file
 shipi18n translate en.json -t es --incremental
+
+# Ollama — fully local, no API key at all (any OpenAI-compatible server works)
+shipi18n translate en.json -p openai --base-url http://localhost:11434/v1 --model llama3.2 -t es
+
+# Google Gemini, via its OpenAI-compatible endpoint
+shipi18n translate en.json -p openai --base-url https://generativelanguage.googleapis.com/v1beta/openai/ \
+  --model gemini-2.5-flash --api-key $GEMINI_API_KEY -t es
 ```
 
 ## Check — validate translations in CI (no LLM, no key)
@@ -107,12 +142,22 @@ 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** (2026-08-16, committed 228-pair corpus, thresholds fixed before the judge was built,
-default judge `claude-haiku-4-5`, 3 passes): **100%** of planted errors caught (100% per category,
-100% label accuracy), **7.1%** false positives on clean pairs, 6/6 glossary violations with 0 false,
-~62k tokens in 141s. 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.
+**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)
 
@@ -167,6 +212,13 @@ A missing or corrupt lock file is a cold start, not a crash.
 Set `ANTHROPIC_API_KEY` (default provider) or use `-p openai` with `OPENAI_API_KEY`. Your keys, your
 models — nothing is sent to a Shipi18n server. Built on [`@shipi18n/core`](https://www.npmjs.com/package/@shipi18n/core).
 
+`--base-url` points the OpenAI provider at **any OpenAI-compatible endpoint**: Ollama
+(`http://localhost:11434/v1` — no key needed, fully offline), Gemini's compatibility endpoint, Groq,
+Mistral, LM Studio, vLLM, or a corporate gateway. It works for `translate` and for the
+`check --semantic` judge alike — pass `--model` for the model that server actually hosts. The judge's
+published accuracy numbers were measured on `claude-haiku-4-5`; before trusting a different judge
+model, run the eval harness in the repo (`evals/semantic/run.mjs`) against it.
+
 ## License
 
 Apache-2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipi18n/cli",
-  "version": "2.3.0",
-  "description": "Open-source, bring-your-own-LLM i18n translation CLI. Translate locale files with your own OpenAI/Anthropic key.",
+  "version": "2.5.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"
@@ -19,6 +19,11 @@
     "access": "public"
   },
   "keywords": [
+    "sarif",
+    "ci",
+    "lint",
+    "translation-quality",
+    "i18n-qa",
     "i18n",
     "cli",
     "translation",
@@ -39,7 +44,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "ora": "^8.0.1",
-    "@shipi18n/core": "^2.3.0"
+    "@shipi18n/core": "^2.5.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.30.0",

package/src/commands/check.js

@@ -73,6 +73,10 @@ export function checkCommand(program) {
     .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(
+      '--base-url <url>',
+      'OpenAI-compatible endpoint for the judge (Ollama, Gemini compat, ...). Needs -p openai; makes the key optional'
+    )
     .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)
@@ -115,10 +119,16 @@ export function checkCommand(program) {
           }
         }
         try {
+          if (opts.baseUrl && opts.provider !== 'openai') {
+            console.error(chalk.red("--base-url targets OpenAI-compatible endpoints. Add -p openai."))
+            process.exitCode = 2
+            return
+          }
           const judge = await runSemantic(result, {
             provider: opts.provider,
             apiKey: opts.apiKey,
             model: opts.semanticModel,
+            baseURL: opts.baseUrl,
             passes: opts.semanticPasses,
             glossary,
             cache,
@@ -132,6 +142,16 @@ export function checkCommand(program) {
                 `${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

package/src/commands/translate.js

@@ -16,6 +16,10 @@ export function translateCommand(program) {
     .option('-p, --provider <name>', 'LLM provider: anthropic | openai', 'anthropic')
     .option('--api-key <key>', 'LLM API key (else read from provider env var)')
     .option('--model <model>', 'Override the provider default model')
+    .option(
+      '--base-url <url>',
+      'OpenAI-compatible endpoint (Ollama, Gemini compat, Groq, a gateway). Needs -p openai; makes the key optional'
+    )
     .option('-i, --incremental', 'Only translate new/missing keys (reuse existing output files)')
     .action(async (input, options) => {
       const provider = options.provider
@@ -23,8 +27,18 @@ export function translateCommand(program) {
         console.error(chalk.red(`Unknown provider '${provider}'. Use 'anthropic' or 'openai'.`))
         process.exit(1)
       }
+      // --base-url speaks the OpenAI wire protocol, so it only makes sense with
+      // the openai adapter. Explicit beats magic: error rather than silently
+      // switching providers out from under the default.
+      if (options.baseUrl && provider !== 'openai') {
+        console.error(chalk.red(`--base-url targets OpenAI-compatible endpoints. Add ${chalk.yellow('-p openai')}.`))
+        console.error(chalk.gray('Works with Ollama (http://localhost:11434/v1), Gemini compat, Groq, LM Studio, vLLM…'))
+        process.exit(1)
+      }
       const apiKey = options.apiKey || process.env[PROVIDER_ENV[provider]]
-      if (!apiKey) {
+      // Local/keyless endpoints (Ollama) need no key; a real provider behind
+      // --base-url will reject the request itself if one was required.
+      if (!apiKey && !options.baseUrl) {
         console.error(chalk.red(`No API key. Set ${chalk.yellow(PROVIDER_ENV[provider])} or pass --api-key.`))
         console.error(chalk.gray(`This tool uses YOUR own ${provider} key — no account or Shipi18n key needed.`))
         process.exit(1)
@@ -61,6 +75,7 @@ export function translateCommand(program) {
             provider,
             apiKey,
             model: options.model,
+            baseURL: options.baseUrl,
             existing,
           })
           writeFileSync(outPath, JSON.stringify(result, null, 2) + '\n', 'utf8')