@shipi18n/core 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @shipi18n/core
 
+## 2.6.0
+
+- New: reporters (`humanReport`, `jsonReport`, `sarifReport`, `junitReport`, `REPORTERS`,
+  `RULE_META`) and `verdict` lifted from the CLI into core, so any surface — the GitHub Action
+  first — can run a full `check` with exit-code semantics and SARIF output without depending on
+  the CLI. The CLI re-exports every name; nothing breaks.
+
+## 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

package/README.md

@@ -36,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.
@@ -95,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,6 +1,6 @@
 {
   "name": "@shipi18n/core",
-  "version": "2.4.0",
+  "version": "2.6.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",
@@ -30,7 +30,10 @@
     "openai",
     "anthropic",
     "localization",
-    "bring-your-own-key"
+    "bring-your-own-key",
+    "linter",
+    "icu",
+    "l10n"
   ],
   "license": "Apache-2.0",
   "author": "Shipi18n",
@@ -54,6 +57,9 @@
   "devDependencies": {
     "jest": "^29.7.0"
   },
+  "dependencies": {
+    "chalk": "^5.3.0"
+  },
   "scripts": {
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --watch"

package/src/adapters/index.js

@@ -70,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 = {}) {
@@ -79,7 +85,17 @@ 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 missingSdkError('openai', 'openai')
         })
@@ -106,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/index.js

@@ -20,3 +20,7 @@ export { parseXcstrings } from './formats/xcstrings.js'
 export { reviewTranslations, DEFAULT_JUDGE_MODELS, buildReviewPrompt, parseVerdicts, pairHash } from './review.js'
 export { getLanguageName, LANGUAGE_NAMES } from './languages.js'
 export { anthropicAdapter, openaiAdapter, resolveAdapter } from './adapters/index.js'
+// Reporters + verdict lived in the CLI through 2.5.x; lifted here (core 2.6.0)
+// so the GitHub Action can run `check` without depending on the CLI. The CLI
+// re-exports these names for compatibility.
+export { humanReport, jsonReport, sarifReport, junitReport, REPORTERS, RULE_META, verdict } from './reporters.js'

package/src/reporters.js

@@ -0,0 +1,217 @@
+/**
+ * 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'
+
+/** 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) {
+  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`))
+  }
+  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
+      ? 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 */
+
+export 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: ruleUrl(t),
+            })),
+          },
+        },
+        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 }
+
+/* ---------------------------------------------------------------- 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 }
+}

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

@@ -320,7 +320,7 @@ export function runCheck({ input, source = 'en', ignoreKeys, glossary, locks } =
  * @returns aggregated judge stats { judged, cached, flagged, calls, parseFailures, excluded }
  */
 
-export async function runSemantic(result, { provider, apiKey, model, passes, glossary, cache, fail = false }) {
+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) {
@@ -346,7 +346,7 @@ 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(stats)) totals[k] = (totals[k] ?? 0) + (stats[k] ?? 0)