@shipi18n/cli 2.4.0 → 2.5.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @shipi18n/cli
 
+## 2.5.1
+
+- New: every check finding now links to its rule page. The human reporter prints
+  `<rule> → https://shipi18n.com/docs/rules/<rule>` for each finding type seen, and the SARIF
+  reporter sets a per-rule `helpUri` — so GitHub's inline PR annotations link to the page that
+  explains the rule, what triggers it, how to fix it, and how to silence it.
+
+## 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

package/README.md

@@ -56,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
 ```
 
@@ -70,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)
@@ -204,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,6 +1,6 @@
 {
   "name": "@shipi18n/cli",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "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": {
@@ -31,7 +31,12 @@
     "openai",
     "anthropic",
     "localization",
-    "bring-your-own-key"
+    "bring-your-own-key",
+    "linter",
+    "icu",
+    "i18next",
+    "l10n",
+    "check"
   ],
   "license": "Apache-2.0",
   "author": "Shipi18n",
@@ -44,7 +49,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "ora": "^8.0.1",
-    "@shipi18n/core": "^2.4.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,

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')

package/src/reporters.js

@@ -6,6 +6,10 @@
  */
 import chalk from 'chalk'
 
+/** Every rule has a documentation page; SARIF helpUri and the human footer
+ *  point at it. Ids must match RULE_META below and the site's checkRules.js. */
+const ruleUrl = (type) => `https://shipi18n.com/docs/rules/${type}`
+
 /* ------------------------------------------------------------------ human */
 
 export function humanReport(result, verdictResult) {
@@ -28,6 +32,13 @@ export function humanReport(result, verdictResult) {
     }
     if (all.length > 50) lines.push(chalk.gray(`    … and ${all.length - 50} more`))
   }
+  const seenTypes = [
+    ...new Set(result.languages.flatMap((l) => l.namespaces.flatMap((n) => n.findings.map((f) => f.type)))),
+  ].sort()
+  if (seenTypes.length > 0) {
+    lines.push('')
+    for (const t of seenTypes) lines.push(chalk.gray(`  ${t} → ${ruleUrl(t)}`))
+  }
   lines.push('')
   lines.push(
     verdictResult.ok
@@ -94,7 +105,7 @@ export function sarifReport(result, _verdictResult, { toolVersion = '0.0.0' } =
             rules: usedTypes.map((t) => ({
               id: t,
               shortDescription: { text: RULE_META[t] || t },
-              helpUri: 'https://shipi18n.com/docs/cli/commands',
+              helpUri: ruleUrl(t),
             })),
           },
         },