@shipi18n/core 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @shipi18n/core
 
+## 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

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.4.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
@@ -63,9 +81,7 @@ export function openaiAdapter(config = {}) {
       clientPromise = import('openai')
         .then(({ default: OpenAI }) => new OpenAI(config.apiKey ? { apiKey: config.apiKey } : {}))
         .catch(() => {
-          throw new Error(
-            "The 'openai' provider requires the 'openai' package. Install it with: npm i openai"
-          )
+          throw missingSdkError('openai', 'openai')
         })
     }
     return clientPromise

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 }
+  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]
     }
@@ -341,7 +348,7 @@ export async function runSemantic(result, { provider, apiKey, model, passes, glo
       source: src, target: tgt, from: result.source, to: l.lang,
       provider, apiKey, model, 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)