@shipi18n/core 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @shipi18n/core
+
+## 2.0.0
+
+Initial open-source release of the **bring-your-own-LLM** translation engine.
+
+- Provider-agnostic adapters: `anthropic` (default, `claude-opus-4-8`), `openai`, or a custom
+  `{ complete }` adapter. Optional peer deps loaded lazily.
+- `translateJSON({ content, from, to, provider, apiKey?, model?, existing? })` — structure-preserving
+  flatten/unflatten, batching, placeholder preserve + validate, and incremental (only-changed) mode.
+- No hosted API and no Shipi18n account — your key calls your LLM directly.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,16 @@
+@shipi18n/core
+Copyright 2025 Shipi18n
+
+This product includes software developed at Shipi18n (https://github.com/Shipi18n).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,71 @@
+# @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.
+
+```bash
+npm i @shipi18n/core @anthropic-ai/sdk   # or: npm i @shipi18n/core openai
+```
+
+## Quickstart
+
+```js
+import { translateJSON } from '@shipi18n/core'
+
+const { result, stats } = await translateJSON({
+  content: { greeting: 'Hello {{name}}', items: 'You have {{count}} items' },
+  from: 'en',
+  to: 'es',
+  provider: 'anthropic',            // 'anthropic' | 'openai' | a custom { complete } adapter
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional — falls back to the provider's env var
+})
+
+console.log(result)  // { greeting: 'Hola {{name}}', items: 'Tienes {{count}} elementos' }
+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.
+
+## What it does
+
+- **Structure-preserving** — flattens/unflattens nested JSON; non-string leaves pass through untouched.
+- **Placeholder-safe** — preserves and validates `{{name}}`, `{count}`, `%s`, `%d`, `%1$s`, `$t(...)`, `%{name}`, and HTML tags.
+- **Batched** — groups strings per request to minimize round-trips.
+- **Incremental** — pass `existing` to reuse prior translations and only translate new/changed keys.
+
+## Incremental translation
+
+```js
+const { result } = await translateJSON({
+  content: source, from: 'en', to: 'fr',
+  provider: 'anthropic',
+  existing: previousFrench,   // only new/empty keys are sent to the LLM
+})
+```
+
+## Custom provider
+
+Any object with a `complete(prompt, opts) => Promise<string>` method works — bring any model:
+
+```js
+const myAdapter = {
+  name: 'my-llm',
+  async complete(prompt) { /* call your model, return its text */ },
+}
+await translateJSON({ content, from: 'en', to: 'de', provider: myAdapter })
+```
+
+## API
+
+- `translateJSON({ content, from, to, provider, apiKey?, model?, existing? })` → `{ result, stats }`
+- `translateStrings(texts, { adapter, from, to, batchSize? })` → `string[]`
+- `flatten(obj)` / `unflatten(flat)`
+- `extractPlaceholders(str)` / `validatePlaceholders(source, translation)`
+- `getLanguageName(code)`
+- `anthropicAdapter(config)` / `openaiAdapter(config)` / `resolveAdapter(provider, config)`
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@shipi18n/core",
+  "version": "2.0.0",
+  "description": "Open-source, bring-your-own-LLM i18n translation engine. Provider-agnostic (OpenAI, Anthropic, ...).",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./adapters": "./src/adapters/index.js"
+  },
+  "files": [
+    "src",
+    "!src/__tests__",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "i18n",
+    "translation",
+    "llm",
+    "openai",
+    "anthropic",
+    "localization",
+    "bring-your-own-key"
+  ],
+  "license": "Apache-2.0",
+  "author": "Shipi18n",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shipi18n/shipi18n.git",
+    "directory": "packages/core"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.114.0",
+    "openai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --watch"
+  }
+}

package/src/adapters/index.js

@@ -0,0 +1,110 @@
+/**
+ * LLM provider adapters. Each adapter exposes a single method:
+ *   complete(prompt: string, opts?: { maxTokens?: number }): Promise<string>
+ *
+ * This is the ONLY provider-specific surface in @shipi18n/core. The translation
+ * engine, prompts, placeholder handling, and batching are all provider-agnostic.
+ *
+ * @typedef {Object} LLMAdapter
+ * @property {(prompt: string, opts?: { maxTokens?: number }) => Promise<string>} complete
+ * @property {string} name
+ */
+
+/**
+ * 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).
+ * @param {{ apiKey?: string, model?: string }} [config]
+ * @returns {LLMAdapter}
+ */
+export function anthropicAdapter(config = {}) {
+  const model = config.model || 'claude-opus-4-8'
+  let clientPromise = null
+  const getClient = async () => {
+    if (!clientPromise) {
+      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"
+          )
+        })
+    }
+    return clientPromise
+  }
+
+  return {
+    name: 'anthropic',
+    async complete(prompt, opts = {}) {
+      const client = await getClient()
+      // Adaptive thinking + generous default; the model decides depth.
+      const res = await client.messages.create({
+        model,
+        max_tokens: opts.maxTokens || 4096,
+        messages: [{ role: 'user', content: prompt }],
+      })
+      const text = (res.content || []).find((b) => b.type === 'text')
+      if (!text) throw new Error('Anthropic response contained no text block')
+      return text.text.trim()
+    },
+  }
+}
+
+/**
+ * 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]
+ * @returns {LLMAdapter}
+ */
+export function openaiAdapter(config = {}) {
+  const model = config.model || 'gpt-4o'
+  let clientPromise = null
+  const getClient = async () => {
+    if (!clientPromise) {
+      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"
+          )
+        })
+    }
+    return clientPromise
+  }
+
+  return {
+    name: 'openai',
+    async complete(prompt, opts = {}) {
+      const client = await getClient()
+      const res = await client.chat.completions.create({
+        model,
+        max_tokens: opts.maxTokens || 4096,
+        messages: [{ role: 'user', content: prompt }],
+      })
+      const content = res.choices?.[0]?.message?.content
+      if (!content) throw new Error('OpenAI response contained no content')
+      return content.trim()
+    },
+  }
+}
+
+/**
+ * Resolve a provider name (+ config) to an adapter instance.
+ * @param {'anthropic'|'openai'|LLMAdapter} provider
+ * @param {{ apiKey?: string, model?: string }} [config]
+ * @returns {LLMAdapter}
+ */
+export function resolveAdapter(provider, config = {}) {
+  if (provider && typeof provider === 'object' && typeof provider.complete === 'function') {
+    return provider // already an adapter (also lets users bring a custom provider)
+  }
+  switch (provider) {
+    case 'anthropic':
+      return anthropicAdapter(config)
+    case 'openai':
+      return openaiAdapter(config)
+    default:
+      throw new Error(
+        `Unknown provider '${provider}'. Use 'anthropic', 'openai', or pass a custom { complete } adapter.`
+      )
+  }
+}

package/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * @shipi18n/core — open-source, bring-your-own-LLM i18n translation engine.
+ *
+ * @example
+ *   import { translateJSON } from '@shipi18n/core'
+ *   const { result } = await translateJSON({
+ *     content: { greeting: 'Hello {{name}}' },
+ *     from: 'en', to: 'es',
+ *     provider: 'anthropic',           // or 'openai', or a custom { complete } adapter
+ *     apiKey: process.env.ANTHROPIC_API_KEY,
+ *   })
+ */
+export { translateJSON, translateStrings, flatten, unflatten } from './translate.js'
+export { extractPlaceholders, validatePlaceholders } from './placeholders.js'
+export { getLanguageName, LANGUAGE_NAMES } from './languages.js'
+export { anthropicAdapter, openaiAdapter, resolveAdapter } from './adapters/index.js'

package/src/languages.js

@@ -0,0 +1,24 @@
+/**
+ * Language code → human-readable name. Ported from the backend so prompts read
+ * naturally ("Translate from English to Spanish") rather than using bare codes.
+ */
+export const LANGUAGE_NAMES = {
+  en: 'English', es: 'Spanish', fr: 'French', de: 'German', it: 'Italian',
+  pt: 'Portuguese', nl: 'Dutch', ru: 'Russian', zh: 'Chinese', 'zh-CN': 'Chinese (Simplified)',
+  'zh-TW': 'Chinese (Traditional)', ja: 'Japanese', ko: 'Korean', ar: 'Arabic', hi: 'Hindi',
+  tr: 'Turkish', pl: 'Polish', vi: 'Vietnamese', th: 'Thai', id: 'Indonesian', ms: 'Malay',
+  sv: 'Swedish', da: 'Danish', no: 'Norwegian', fi: 'Finnish', cs: 'Czech', sk: 'Slovak',
+  hu: 'Hungarian', ro: 'Romanian', bg: 'Bulgarian', uk: 'Ukrainian', el: 'Greek',
+  he: 'Hebrew', fa: 'Persian',
+}
+
+/**
+ * @param {string} code e.g. "es" or "pt-BR"
+ * @returns {string} the language name, falling back to the base code, then the code
+ */
+export function getLanguageName(code) {
+  if (!code) return code
+  if (LANGUAGE_NAMES[code]) return LANGUAGE_NAMES[code]
+  const base = code.split('-')[0]
+  return LANGUAGE_NAMES[base] || code
+}

package/src/placeholders.js

@@ -0,0 +1,70 @@
+/**
+ * Placeholder detection + validation.
+ *
+ * i18n strings embed placeholders that must survive translation byte-for-byte:
+ *   - i18next / ICU:  {{name}}, {count}
+ *   - printf:         %s, %d, %1$s
+ *   - i18next nesting: $t(some.key)
+ *   - React-intl:     {name}
+ *   - Ruby / others:  %{name}
+ *
+ * The translation prompt instructs the model to preserve these; these helpers
+ * VERIFY the model obeyed, so callers can retry or flag drift.
+ */
+
+const PLACEHOLDER_PATTERNS = [
+  /\{\{[^}]+\}\}/g, // {{name}}
+  /\$t\([^)]*\)/g, // $t(key)
+  /%\{[^}]+\}/g, // %{name}
+  /%\d+\$[sdfx]/g, // %1$s
+  /%[sdfx]/g, // %s %d
+  /\{[a-zA-Z0-9_.]+\}/g, // {count} {name}  (after the {{ }} pass)
+]
+
+/**
+ * Extract all placeholders from a string, in a stable, comparable multiset.
+ * @param {string} str
+ * @returns {string[]} sorted list of placeholder tokens (duplicates preserved)
+ */
+export function extractPlaceholders(str) {
+  if (typeof str !== 'string') return []
+  let working = str
+  const found = []
+  for (const pattern of PLACEHOLDER_PATTERNS) {
+    const matches = working.match(pattern) || []
+    for (const m of matches) found.push(m)
+    // blank out matched spans so later, looser patterns don't double-count
+    working = working.replace(pattern, (m) => ' '.repeat(m.length))
+  }
+  return found.sort()
+}
+
+/**
+ * Does the translation preserve exactly the placeholders of the source?
+ * @param {string} source
+ * @param {string} translation
+ * @returns {{ ok: boolean, missing: string[], added: string[] }}
+ */
+export function validatePlaceholders(source, translation) {
+  const src = extractPlaceholders(source)
+  const out = extractPlaceholders(translation)
+  const outCounts = tally(out)
+  const srcCounts = tally(src)
+  const missing = []
+  const added = []
+  for (const [ph, n] of Object.entries(srcCounts)) {
+    const diff = n - (outCounts[ph] || 0)
+    for (let i = 0; i < diff; i++) missing.push(ph)
+  }
+  for (const [ph, n] of Object.entries(outCounts)) {
+    const diff = n - (srcCounts[ph] || 0)
+    for (let i = 0; i < diff; i++) added.push(ph)
+  }
+  return { ok: missing.length === 0 && added.length === 0, missing, added }
+}
+
+function tally(arr) {
+  const t = {}
+  for (const x of arr) t[x] = (t[x] || 0) + 1
+  return t
+}

package/src/translate.js

@@ -0,0 +1,167 @@
+/**
+ * Core translation engine — provider-agnostic. Ported from the backend's
+ * context-aware Claude path, with the single `client.messages.create` call
+ * replaced by an injected LLMAdapter.
+ */
+import { resolveAdapter } from './adapters/index.js'
+import { getLanguageName } from './languages.js'
+import { validatePlaceholders } from './placeholders.js'
+
+const BATCH_PROMPT = `You are a professional software localizer. Translate each UI string accurately.
+
+Translate from {SOURCE_LANG} to {TARGET_LANG}.
+
+STRINGS TO TRANSLATE (JSON array):
+{TEXTS}
+
+Requirements:
+1. Preserve ALL placeholders exactly as they appear: {{name}}, {count}, %s, %d, %1$s, $t(...), %{name}.
+2. Do not translate placeholder contents, HTML tags, or code.
+3. Keep the tone appropriate for application UI (concise, natural).
+4. Return ONLY a JSON array of translated strings, in the same order and length as the input. No prose, no markdown fences.`
+
+/**
+ * Flatten a nested object into dot-path → string entries (arrays indexed).
+ * Non-string leaves (numbers, booleans, null) are left in place and not translated.
+ */
+export function flatten(obj, prefix = '', out = {}) {
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      flatten(value, path, out)
+    } else if (Array.isArray(value)) {
+      value.forEach((v, i) => {
+        if (v && typeof v === 'object') flatten(v, `${path}.${i}`, out)
+        else out[`${path}.${i}`] = v
+      })
+    } else {
+      out[path] = value
+    }
+  }
+  return out
+}
+
+/** Rebuild a nested object from dot-path entries. */
+export function unflatten(flat) {
+  const root = {}
+  for (const [path, value] of Object.entries(flat)) {
+    const parts = path.split('.')
+    let node = root
+    for (let i = 0; i < parts.length - 1; i++) {
+      const key = parts[i]
+      const nextIsIndex = /^\d+$/.test(parts[i + 1])
+      if (node[key] == null) node[key] = nextIsIndex ? [] : {}
+      node = node[key]
+    }
+    node[parts[parts.length - 1]] = value
+  }
+  return root
+}
+
+function parseJsonArray(text, expectedLength) {
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    const match = text.match(/\[[\s\S]*\]/)
+    if (!match) throw new Error('LLM did not return a JSON array')
+    parsed = JSON.parse(match[0])
+  }
+  if (!Array.isArray(parsed) || parsed.length !== expectedLength) {
+    throw new Error(`Expected ${expectedLength} translations, got ${parsed?.length ?? 0}`)
+  }
+  return parsed
+}
+
+function chunk(arr, size) {
+  const out = []
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size))
+  return out
+}
+
+/**
+ * Translate a batch of strings via the adapter.
+ * @param {string[]} texts
+ * @param {object} opts { adapter, from, to, batchSize }
+ * @returns {Promise<string[]>}
+ */
+export async function translateStrings(texts, { adapter, from, to, batchSize = 40 }) {
+  const results = new Array(texts.length)
+  const batches = chunk(
+    texts.map((t, i) => ({ t, i })),
+    batchSize
+  )
+  for (const batch of batches) {
+    const prompt = BATCH_PROMPT
+      .replace('{SOURCE_LANG}', getLanguageName(from))
+      .replace('{TARGET_LANG}', getLanguageName(to))
+      .replace('{TEXTS}', JSON.stringify(batch.map((b) => b.t), null, 2))
+    const raw = await adapter.complete(prompt, { maxTokens: 8192 })
+    const translated = parseJsonArray(raw, batch.length)
+    batch.forEach((b, idx) => {
+      results[b.i] = translated[idx]
+    })
+  }
+  return results
+}
+
+/**
+ * Translate a locale JSON object from one language to another, preserving
+ * structure and placeholders. BYO-LLM: pass provider + key (or a custom adapter).
+ *
+ * @param {object} params
+ * @param {Record<string, any>} params.content   source locale object
+ * @param {string} params.from                   source language code
+ * @param {string} params.to                     target language code
+ * @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 {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 })
+  const sourceFlat = flatten(content)
+  const existingFlat = existing ? flatten(existing) : {}
+
+  // Incremental: only translate keys that are new or whose source presumably changed.
+  // (Without a stored source snapshot we treat "already has a translation" as reusable;
+  //  callers that track source hashes can pass a filtered `existing`.)
+  const entries = Object.entries(sourceFlat)
+  const toTranslate = []
+  const outFlat = {}
+  for (const [path, value] of entries) {
+    if (typeof value !== 'string') {
+      outFlat[path] = value // non-string leaves pass through untouched
+    } else if (existingFlat[path] != null && existingFlat[path] !== '') {
+      outFlat[path] = existingFlat[path] // reuse prior translation
+    } else {
+      toTranslate.push({ path, value })
+    }
+  }
+
+  const placeholderWarnings = []
+  if (toTranslate.length > 0) {
+    const translated = await translateStrings(
+      toTranslate.map((e) => e.value),
+      { adapter, from, to }
+    )
+    toTranslate.forEach((e, i) => {
+      const out = translated[i]
+      outFlat[e.path] = out
+      const check = validatePlaceholders(e.value, out)
+      if (!check.ok) {
+        placeholderWarnings.push({ path: e.path, source: e.value, translation: out, ...check })
+      }
+    })
+  }
+
+  return {
+    result: unflatten(outFlat),
+    stats: {
+      translated: toTranslate.length,
+      reused: entries.length - toTranslate.length - entries.filter(([, v]) => typeof v !== 'string').length,
+      placeholderWarnings,
+    },
+  }
+}