@shipi18n/core 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @shipi18n/core
 
+## 2.5.0
+
+- New: the `openai` adapter accepts `baseURL`, pointing it at any OpenAI-compatible endpoint —
+  Ollama (no key needed, fully offline), Gemini's compatibility endpoint, Groq, Mistral, LM Studio,
+  vLLM, corporate gateways. `translateJSON`, `reviewTranslations` and `runSemantic` all take and
+  thread it through. When a `baseURL` is set and no key is given, a placeholder key is sent instead
+  of failing, since servers like Ollama accept anything.
+
+## 2.4.0
+
+- Fix: `runSemantic` now returns `excluded` — the number of pairs it skipped because the key already
+  carried a structural error. Without it a fully-broken tree reported `judged 0` and was
+  indistinguishable from a clean one, which reads as a dead feature rather than correct behaviour.
+- Fix: the missing-SDK error names a fix that actually works. `npm i @anthropic-ai/sdk` does nothing
+  for the `npx @shipi18n/cli` path — that copy of the CLI resolves imports against npm's cache, not
+  your project — so the message now says to install the SDK next to the CLI and run `npx shipi18n`.
+- Note: the npm description on this page was stale until this release. npm only refreshes it on
+  publish, so the registry still described a translation engine after the project had repositioned
+  around translation QA.
+
 ## 2.3.0
 
 - New: manual-translation locks (`lockId`, `lockEntry`, `lockFinding`, `normalizeLocks`) — record

package/README.md

@@ -1,11 +1,19 @@
 # @shipi18n/core
 
-Open-source, **bring-your-own-LLM** i18n translation engine. Translate locale JSON with your own
-OpenAI or Anthropic key — no Shipi18n account, no hosted API, no per-word fees. Provider-agnostic and
-extensible.
+**The engine behind Shipi18n's translation QA** — placeholder and plural validation, key parity,
+coverage and an LLM-as-judge semantic review — plus a structure-preserving translation engine. Open
+source, **bring your own LLM**, no account and no hosted API.
 
 ```bash
-npm i @shipi18n/core @anthropic-ai/sdk   # or: npm i @shipi18n/core openai
+npm i @shipi18n/core                     # checking needs nothing else
+npm i @shipi18n/core @anthropic-ai/sdk   # add a provider SDK to translate or judge
+```
+
+```js
+import { runCheck } from '@shipi18n/core'
+
+// deterministic, no model, no key
+const { languages, totals } = runCheck({ input: './locales', source: 'en' })
 ```
 
 ## Quickstart
@@ -28,6 +36,19 @@ console.log(stats)   // { translated, reused, placeholderWarnings }
 The API key is resolved from `apiKey` or, if omitted, the provider's env var
 (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`). Your key is used to call **your** LLM directly.
 
+The `openai` provider also takes a `baseURL`, which points it 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:
+
+```js
+await translateJSON({
+  content, from: 'en', to: 'es',
+  provider: 'openai',
+  baseURL: 'http://localhost:11434/v1',  // Ollama — no apiKey required
+  model: 'llama3.2',
+})
+```
+
 ## What it does
 
 - **Structure-preserving** — flattens/unflattens nested JSON; non-string leaves pass through untouched.
@@ -87,7 +108,7 @@ Format adapters for mobile catalogs are exported too: `parseArbBundle` (Flutter
 
 ## API
 
-- `translateJSON({ content, from, to, provider, apiKey?, model?, existing? })` → `{ result, stats }`
+- `translateJSON({ content, from, to, provider, apiKey?, model?, baseURL?, existing? })` → `{ result, stats }`
 - `translateStrings(texts, { adapter, from, to, batchSize? })` → `string[]`
 - `flatten(obj)` / `unflatten(flat)`
 - `extractPlaceholders(str)` / `validatePlaceholders(source, translation)`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipi18n/core",
-  "version": "2.3.0",
-  "description": "Open-source, bring-your-own-LLM i18n translation engine. Provider-agnostic (OpenAI, Anthropic, ...).",
+  "version": "2.5.0",
+  "description": "Translation QA for i18n locale files: placeholder and plural validation, key parity, coverage, and an LLM-as-judge semantic review. Also a structure-preserving translation engine — bring your own OpenAI or Anthropic key.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -20,6 +20,10 @@
     "access": "public"
   },
   "keywords": [
+    "validation",
+    "lint",
+    "translation-quality",
+    "i18n-qa",
     "i18n",
     "translation",
     "llm",

package/src/adapters/index.js

@@ -10,6 +10,26 @@
  * @property {string} name
  */
 
+/**
+ * The SDKs are optional peer deps, so a missing one is the single most common
+ * first-run failure. Naming `npm i <sdk>` alone is a trap for the npx path:
+ * `npx @shipi18n/cli` runs the CLI out of npm's throwaway cache, which resolves
+ * imports against itself and never sees the project's node_modules. The only
+ * fix that works there is installing both, then running the local binary.
+ * @param {string} provider
+ * @param {string} sdk
+ * @returns {Error}
+ */
+function missingSdkError(provider, sdk) {
+  return new Error(
+    `The '${provider}' provider requires the '${sdk}' package.\n` +
+      `  Install it next to the CLI:  npm i -D @shipi18n/cli ${sdk}\n` +
+      `  then run:                    npx shipi18n <command>\n` +
+      `  If you ran 'npx @shipi18n/cli', installing ${sdk} on its own will not help — ` +
+      `that copy of the CLI cannot see your project's node_modules.`
+  )
+}
+
 /**
  * Anthropic Claude adapter. Requires the optional peer dep `@anthropic-ai/sdk`.
  * Key resolved from opts.apiKey or the ANTHROPIC_API_KEY env var (SDK default).
@@ -24,9 +44,7 @@ export function anthropicAdapter(config = {}) {
       clientPromise = import('@anthropic-ai/sdk')
         .then(({ default: Anthropic }) => new Anthropic(config.apiKey ? { apiKey: config.apiKey } : {}))
         .catch(() => {
-          throw new Error(
-            "The 'anthropic' provider requires the '@anthropic-ai/sdk' package. Install it with: npm i @anthropic-ai/sdk"
-          )
+          throw missingSdkError('anthropic', '@anthropic-ai/sdk')
         })
     }
     return clientPromise
@@ -52,7 +70,13 @@ export function anthropicAdapter(config = {}) {
 /**
  * OpenAI adapter. Requires the optional peer dep `openai`.
  * Key resolved from opts.apiKey or the OPENAI_API_KEY env var (SDK default).
- * @param {{ apiKey?: string, model?: string }} [config]
+ *
+ * `baseURL` points the same adapter at any OpenAI-compatible endpoint —
+ * Ollama (http://localhost:11434/v1), Gemini's compatibility endpoint, Groq,
+ * Mistral, LM Studio, vLLM, a corporate gateway. Servers like Ollama accept
+ * any key, but the SDK refuses to construct without one, so when a baseURL is
+ * given and no key is, we pass a placeholder instead of failing the run.
+ * @param {{ apiKey?: string, model?: string, baseURL?: string }} [config]
  * @returns {LLMAdapter}
  */
 export function openaiAdapter(config = {}) {
@@ -61,11 +85,19 @@ export function openaiAdapter(config = {}) {
   const getClient = async () => {
     if (!clientPromise) {
       clientPromise = import('openai')
-        .then(({ default: OpenAI }) => new OpenAI(config.apiKey ? { apiKey: config.apiKey } : {}))
+        .then(
+          ({ default: OpenAI }) =>
+            new OpenAI({
+              ...(config.apiKey
+                ? { apiKey: config.apiKey }
+                : config.baseURL
+                  ? { apiKey: 'not-needed' } // local/keyless endpoints; real ones will 401
+                  : {}), // no baseURL: keep SDK default (OPENAI_API_KEY env)
+              ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+            })
+        )
         .catch(() => {
-          throw new Error(
-            "The 'openai' provider requires the 'openai' package. Install it with: npm i openai"
-          )
+          throw missingSdkError('openai', 'openai')
         })
     }
     return clientPromise
@@ -90,7 +122,7 @@ export function openaiAdapter(config = {}) {
 /**
  * Resolve a provider name (+ config) to an adapter instance.
  * @param {'anthropic'|'openai'|LLMAdapter} provider
- * @param {{ apiKey?: string, model?: string }} [config]
+ * @param {{ apiKey?: string, model?: string, baseURL?: string }} [config]
  * @returns {LLMAdapter}
  */
 export function resolveAdapter(provider, config = {}) {

package/src/review.js

@@ -118,10 +118,11 @@ export async function reviewTranslations({
   passes = 3,
   glossary,
   cache,
+  baseURL,
 }) {
   const judgeModel =
     model ?? (typeof provider === 'string' ? DEFAULT_JUDGE_MODELS[provider] : undefined)
-  const adapter = resolveAdapter(provider, { apiKey, model: judgeModel })
+  const adapter = resolveAdapter(provider, { apiKey, model: judgeModel, baseURL })
 
   const src = flatten(source)
   const tgt = flatten(target)

package/src/translate.js

@@ -116,11 +116,12 @@ export async function translateStrings(texts, { adapter, from, to, batchSize = 4
  * @param {'anthropic'|'openai'|object} params.provider  provider name or a custom adapter
  * @param {string} [params.apiKey]               LLM API key (else provider env var)
  * @param {string} [params.model]                override the provider's default model
+ * @param {string} [params.baseURL]              OpenAI-compatible endpoint override (Ollama, Gemini compat, ...)
  * @param {Record<string,any>} [params.existing] prior translation → only re-translate changed/new keys (incremental)
  * @returns {Promise<{ result: object, stats: { translated: number, reused: number, placeholderWarnings: Array }}>}
  */
-export async function translateJSON({ content, from, to, provider, apiKey, model, existing }) {
-  const adapter = resolveAdapter(provider, { apiKey, model })
+export async function translateJSON({ content, from, to, provider, apiKey, model, baseURL, existing }) {
+  const adapter = resolveAdapter(provider, { apiKey, model, baseURL })
   const sourceFlat = flatten(content)
   const existingFlat = existing ? flatten(existing) : {}
 

package/src/tree.js

@@ -313,11 +313,15 @@ export function runCheck({ input, source = 'en', ignoreKeys, glossary, locks } =
  * placeholder. Semantic findings are WARNINGS unless `fail` is set; a noisy
  * gate that blocks PRs gets uninstalled.
  *
- * @returns aggregated judge stats { judged, cached, flagged, calls, parseFailures }
+ * `excluded` counts the pairs skipped for that reason. It exists so callers can
+ * tell "nothing was wrong" apart from "everything was too wrong to judge" — a
+ * fully-broken tree otherwise reports `judged 0` and reads like a dead feature.
+ *
+ * @returns aggregated judge stats { judged, cached, flagged, calls, parseFailures, excluded }
  */
 
-export async function runSemantic(result, { provider, apiKey, model, passes, glossary, cache, fail = false }) {
-  const totals = { judged: 0, cached: 0, flagged: 0, calls: 0, parseFailures: 0 }
+export async function runSemantic(result, { provider, apiKey, model, baseURL, passes, glossary, cache, fail = false }) {
+  const totals = { judged: 0, cached: 0, flagged: 0, calls: 0, parseFailures: 0, excluded: 0 }
 
   for (const l of result.languages) {
     const pairs = result.semanticPairs?.[l.lang]
@@ -331,7 +335,10 @@ export async function runSemantic(result, { provider, apiKey, model, passes, glo
     const src = {}
     const tgt = {}
     for (const key of Object.keys(pairs.source)) {
-      if (errorPaths.has(key)) continue
+      if (errorPaths.has(key)) {
+        totals.excluded++
+        continue
+      }
       src[key] = pairs.source[key]
       tgt[key] = pairs.target[key]
     }
@@ -339,9 +346,9 @@ export async function runSemantic(result, { provider, apiKey, model, passes, glo
 
     const { findings, stats } = await reviewTranslations({
       source: src, target: tgt, from: result.source, to: l.lang,
-      provider, apiKey, model, passes, glossary, cache,
+      provider, apiKey, model, baseURL, passes, glossary, cache,
     })
-    for (const k of Object.keys(totals)) totals[k] += stats[k] ?? 0
+    for (const k of Object.keys(stats)) totals[k] = (totals[k] ?? 0) + (stats[k] ?? 0)
 
     for (const f of findings) {
       const sepAt = f.path.indexOf(SEP)