@shipi18n/core 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @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

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.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",

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