rosetta-i18n 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Hunter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# Rosetta i18n
+
+Self-hosted AI translation engine. One text, every language — translate key-value content across locales through any OpenAI-compatible LLM, with brand voice and glossary enforcement.
+
+Named after the Rosetta Stone: one text, three scripts, every language readable.
+
+No vendor lock-in and no per-seat translation SaaS — bring your own LLM endpoint and API key.
+
+## Install
+
+```bash
+pnpm add rosetta-i18n
+# or
+npm install rosetta-i18n
+```
+
+## Quick start
+
+```ts
+import { Rosetta } from "rosetta-i18n";
+
+const rosetta = new Rosetta({
+	apiKey: process.env.OPENROUTER_API_KEY,
+	model: "anthropic/claude-sonnet-4.5",
+	brandVoice: {
+		variations: {
+			"*": "Confident, precise, editorial. Short sentences, active voice.",
+			es: "Tono editorial de gastronomía, accesible. Tercera persona.",
+		},
+	},
+	glossary: {
+		es: { "award-winning": "premiado" },
+	},
+});
+
+const translated = await rosetta.translate(
+	{ hero: "Every awarded restaurant in the world" },
+	{ source: "en", target: "es" },
+);
+```
+
+### Single strings
+
+```ts
+const text = await rosetta.translateText("Every awarded restaurant", {
+	source: "en",
+	target: "ja",
+});
+```
+
+## How it works
+
+Every request is sent to an OpenAI-compatible `/chat/completions` endpoint
+(OpenRouter by default). The system prompt layers three signals, in this
+precedence:
+
+1. **Glossary** — exact term match, overrides model judgment
+2. **Rules** — locale-specific conventions embedded in the brand voice
+3. **Brand voice** — sets overall tone per locale
+
+The user prompt carries the payload plus optional broad context and per-key
+disambiguation hints.
+
+## API
+
+### `new Rosetta(config)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | — | **Required.** Key for the LLM endpoint. |
+| `model` | `string` | — | **Required.** Model id, e.g. `anthropic/claude-sonnet-4.5`. |
+| `brandVoice` | `BrandVoice` | — | **Required.** Tone + conventions per locale. `*` is the fallback. |
+| `baseURL` | `string` | `https://openrouter.ai/api/v1` | Any OpenAI-compatible endpoint. |
+| `glossary` | `Glossary` | `{}` | Exact term mappings per locale. |
+| `temperature` | `number` | `0.3` | Sampling temperature. |
+| `batchSize` | `number` | `25` | Keys per LLM request. |
+| `concurrency` | `number` | `4` | Parallel batch requests in flight. |
+| `retries` | `number` | `2` | Retries per batch on failure. |
+
+### `rosetta.translate(data, options)`
+
+Translates a key-value payload. Keys are preserved; only values are translated.
+Batches run concurrently and failed batches are logged and skipped, so the
+result carries only successfully translated keys — the caller can fall back to
+the source locale for the rest.
+
+```ts
+const out = await rosetta.translate(
+	{ hero: "…", subhead: "…" },
+	{
+		source: "en",
+		target: "pt-BR",
+		context: "restaurant listing page",
+		hints: { hero: ["home", "top banner"] },
+	},
+);
+```
+
+### `rosetta.translateText(text, options)`
+
+Translates a single string. Throws on a non-OK response (unlike `translate`,
+which degrades gracefully at the batch level).
+
+## Releasing
+
+Releases publish automatically from GitHub Actions via npm
+[trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) — no npm
+token required.
+
+```bash
+pnpm bump patch   # bump package.json, commit, tag, push
+pnpm release      # create the GitHub Release -> triggers npm-publish
+```
+
+- `pnpm bump` accepts `patch`, `minor`, or `major` (default `patch`).
+- `pnpm release` creates the GitHub Release for the latest tag with generated
+  release notes, which triggers `.github/workflows/npm-publish.yml`.
+
+One-time setup (first publish and Trusted Publisher) is documented in
+[`.github/workflows/npm-publish.yml`](.github/workflows/npm-publish.yml).
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+Source lives in `src/`. `rollup` produces `dist/esm`, `tsc` emits declarations
+to `dist/types`.
+
+## License
+
+MIT © Ian Hunter

package/dist/esm/index.js

@@ -0,0 +1,160 @@
+function buildSystemPrompt(options) {
+  const { brandVoice, glossary, source, target } = options;
+  const voice = brandVoice.variations[target] ?? brandVoice.variations["*"] ?? "";
+  const parts = [voice];
+  if (glossary) {
+    const terms = glossary[target];
+    if (terms && Object.keys(terms).length > 0) {
+      parts.push(
+        `Glossary (use these exact renderings):
+${Object.entries(terms).map(([src, tgt]) => `- "${src}" -> ${tgt}`).join("\n")}`
+      );
+    }
+  }
+  parts.push(
+    `Translate from ${source} to ${target}. Return ONLY the translated text \u2014 no explanations, no quotes around it.`
+  );
+  return parts.filter(Boolean).join("\n\n");
+}
+function buildDataPrompt(data, options) {
+  const lines = [
+    `Translate the values of this JSON object from ${options.source} to ${options.target}. Keep every key exactly as provided \u2014 return a JSON object with identical keys and translated values. Preserve {placeholders} and ICU plural syntax (=1 {...} other {...}) intact, translating only the inner text. Output ONLY the JSON.`
+  ];
+  if (options.context) {
+    lines.push(`Context: ${options.context}`);
+  }
+  if (options.hints) {
+    const hints = Object.entries(options.hints).map(([key, breadcrumb]) => `- ${key}: ${breadcrumb.join(" > ")}`).join("\n");
+    if (hints) {
+      lines.push(`Key disambiguation:
+${hints}`);
+    }
+  }
+  lines.push(JSON.stringify(data, null, 1));
+  return lines.join("\n\n");
+}
+
+class Rosetta {
+  config;
+  constructor(config) {
+    if (!config.apiKey) throw new Error("Rosetta: apiKey is required");
+    if (!config.model) throw new Error("Rosetta: model is required");
+    this.config = config;
+  }
+  /** Translate a single text string. */
+  async translateText(text, options) {
+    const system = buildSystemPrompt({
+      brandVoice: this.config.brandVoice,
+      glossary: this.config.glossary,
+      source: options.source,
+      target: options.target
+    });
+    const res = await this.chat([
+      { role: "system", content: system },
+      {
+        role: "user",
+        content: options.context ? `${text}
+
+Context: ${options.context}` : text
+      }
+    ]);
+    if (!res.ok) {
+      throw new Error(`Rosetta: ${res.status} ${await res.text()}`);
+    }
+    const json = await res.json();
+    return json.choices[0].message.content.trim();
+  }
+  /**
+   * Translate a key-value payload, batched with concurrency. Failed batches
+   * are logged and skipped — the returned object carries only successfully
+   * translated keys, letting the caller fall back to the source locale for
+   * the rest.
+   */
+  async translate(data, options) {
+    const batchSize = this.config.batchSize ?? 25;
+    const concurrency = this.config.concurrency ?? 4;
+    const keys = Object.keys(data);
+    const output = {};
+    for (let i = 0; i < keys.length; i += batchSize * concurrency) {
+      const chunk = keys.slice(i, i + batchSize * concurrency);
+      const batches = Array.from(
+        { length: Math.ceil(chunk.length / batchSize) },
+        (_, b) => {
+          const batchKeys = chunk.slice(b * batchSize, (b + 1) * batchSize);
+          const batch = Object.fromEntries(batchKeys.map((k) => [k, data[k]]));
+          return { batch, batchKeys };
+        }
+      );
+      const results = await Promise.allSettled(
+        batches.map(
+          ({ batch, batchKeys }) => this.translateBatch(batch, options, batchKeys)
+        )
+      );
+      for (let b = 0; b < results.length; b++) {
+        const result = results[b];
+        if (result.status !== "fulfilled") {
+          console.error(
+            `[rosetta] batch failed (${batches[b].batchKeys.length} keys):`,
+            result.reason?.message?.slice(0, 120)
+          );
+          continue;
+        }
+        Object.assign(output, result.value);
+      }
+    }
+    return output;
+  }
+  async translateBatch(batch, options, batchKeys) {
+    const retries = this.config.retries ?? 2;
+    const system = buildSystemPrompt({
+      brandVoice: this.config.brandVoice,
+      glossary: this.config.glossary,
+      source: options.source,
+      target: options.target
+    });
+    const user = buildDataPrompt(batch, {
+      ...options,
+      hints: options.hints ? Object.fromEntries(
+        batchKeys.map((key) => [key, options.hints?.[key] ?? []])
+      ) : void 0
+    });
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const res = await this.chat([
+          { role: "system", content: system },
+          { role: "user", content: user }
+        ]);
+        if (!res.ok) {
+          throw new Error(`Rosetta: ${res.status} ${await res.text()}`);
+        }
+        const json = await res.json();
+        return JSON.parse(json.choices[0].message.content);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt < retries) {
+          await new Promise((ok) => setTimeout(ok, 2e3 * (attempt + 1)));
+        }
+      }
+    }
+    throw lastError ?? new Error("Rosetta: batch failed");
+  }
+  async chat(messages) {
+    const baseURL = this.config.baseURL ?? "https://openrouter.ai/api/v1";
+    return fetch(`${baseURL}/chat/completions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        model: this.config.model,
+        temperature: this.config.temperature ?? 0.3,
+        messages
+      })
+    });
+  }
+}
+
+export { Rosetta };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../src/prompt.ts","../../src/index.ts"],"sourcesContent":["import type { BrandVoice, Glossary, TranslateDataOptions } from \"./config\";\n\n/**\n * Builds the system prompt for a translation request: brand voice, glossary\n * enforcement, locale conventions, and output-shape rules.\n */\nexport function buildSystemPrompt(options: {\n\tbrandVoice: BrandVoice;\n\tglossary?: Glossary;\n\tsource: string;\n\ttarget: string;\n}): string {\n\tconst { brandVoice, glossary, source, target } = options;\n\n\tconst voice =\n\t\tbrandVoice.variations[target] ?? brandVoice.variations[\"*\"] ?? \"\";\n\n\tconst parts = [voice];\n\n\tif (glossary) {\n\t\tconst terms = glossary[target];\n\t\tif (terms && Object.keys(terms).length > 0) {\n\t\t\tparts.push(\n\t\t\t\t`Glossary (use these exact renderings):\\n${Object.entries(terms)\n\t\t\t\t\t.map(([src, tgt]) => `- \"${src}\" -> ${tgt}`)\n\t\t\t\t\t.join(\"\\n\")}`,\n\t\t\t);\n\t\t}\n\t}\n\n\tparts.push(\n\t\t`Translate from ${source} to ${target}. Return ONLY the translated text — no explanations, no quotes around it.`,\n\t);\n\n\treturn parts.filter(Boolean).join(\"\\n\\n\");\n}\n\n/**\n * Builds the user prompt for a key-value payload translation.\n */\nexport function buildDataPrompt(\n\tdata: Record<string, unknown>,\n\toptions: TranslateDataOptions & { hints?: Record<string, string[]> },\n): string {\n\tconst lines = [\n\t\t`Translate the values of this JSON object from ${options.source} to ${options.target}. Keep every key exactly as provided — return a JSON object with identical keys and translated values. Preserve {placeholders} and ICU plural syntax (=1 {...} other {...}) intact, translating only the inner text. Output ONLY the JSON.`,\n\t];\n\n\tif (options.context) {\n\t\tlines.push(`Context: ${options.context}`);\n\t}\n\n\tif (options.hints) {\n\t\tconst hints = Object.entries(options.hints)\n\t\t\t.map(([key, breadcrumb]) => `- ${key}: ${breadcrumb.join(\" > \")}`)\n\t\t\t.join(\"\\n\");\n\t\tif (hints) {\n\t\t\tlines.push(`Key disambiguation:\\n${hints}`);\n\t\t}\n\t}\n\n\tlines.push(JSON.stringify(data, null, 1));\n\n\treturn lines.join(\"\\n\\n\");\n}\n","import type {\n\tRosettaConfig,\n\tTranslateDataOptions,\n\tTranslateTextOptions,\n} from \"./config\";\nimport { buildDataPrompt, buildSystemPrompt } from \"./prompt\";\n\nexport type {\n\tRosettaConfig,\n\tTranslateDataOptions,\n\tTranslateTextOptions,\n} from \"./config\";\n\ninterface ChatMessage {\n\trole: \"system\" | \"user\" | \"assistant\";\n\tcontent: string;\n}\n\n/**\n * Rosetta — self-hosted AI translation engine.\n *\n * Translates key-value content across locales through any OpenAI-compatible\n * LLM, with brand voice, glossary, and per-locale rules applied on every\n * call. Works with OpenRouter, direct Anthropic/OpenAI, or any\n * OpenAI-compatible endpoint.\n *\n * Non-throwing at the batch level: failed batches are logged and skipped, so\n * partial translations degrade gracefully to the source locale.\n */\nexport class Rosetta {\n\tprivate config: RosettaConfig;\n\n\tconstructor(config: RosettaConfig) {\n\t\tif (!config.apiKey) throw new Error(\"Rosetta: apiKey is required\");\n\t\tif (!config.model) throw new Error(\"Rosetta: model is required\");\n\t\tthis.config = config;\n\t}\n\n\t/** Translate a single text string. */\n\tasync translateText(\n\t\ttext: string,\n\t\toptions: TranslateTextOptions,\n\t): Promise<string> {\n\t\tconst system = buildSystemPrompt({\n\t\t\tbrandVoice: this.config.brandVoice,\n\t\t\tglossary: this.config.glossary,\n\t\t\tsource: options.source,\n\t\t\ttarget: options.target,\n\t\t});\n\n\t\tconst res = await this.chat([\n\t\t\t{ role: \"system\", content: system },\n\t\t\t{\n\t\t\t\trole: \"user\",\n\t\t\t\tcontent: options.context\n\t\t\t\t\t? `${text}\\n\\nContext: ${options.context}`\n\t\t\t\t\t: text,\n\t\t\t},\n\t\t]);\n\n\t\tif (!res.ok) {\n\t\t\tthrow new Error(`Rosetta: ${res.status} ${await res.text()}`);\n\t\t}\n\t\tconst json = (await res.json()) as {\n\t\t\tchoices: Array<{ message: { content: string } }>;\n\t\t};\n\t\treturn json.choices[0].message.content.trim();\n\t}\n\n\t/**\n\t * Translate a key-value payload, batched with concurrency. Failed batches\n\t * are logged and skipped — the returned object carries only successfully\n\t * translated keys, letting the caller fall back to the source locale for\n\t * the rest.\n\t */\n\tasync translate(\n\t\tdata: Record<string, unknown>,\n\t\toptions: TranslateDataOptions,\n\t): Promise<Record<string, unknown>> {\n\t\tconst batchSize = this.config.batchSize ?? 25;\n\t\tconst concurrency = this.config.concurrency ?? 4;\n\t\tconst keys = Object.keys(data);\n\t\tconst output: Record<string, unknown> = {};\n\n\t\tfor (let i = 0; i < keys.length; i += batchSize * concurrency) {\n\t\t\tconst chunk = keys.slice(i, i + batchSize * concurrency);\n\t\t\tconst batches = Array.from(\n\t\t\t\t{ length: Math.ceil(chunk.length / batchSize) },\n\t\t\t\t(_, b) => {\n\t\t\t\t\tconst batchKeys = chunk.slice(b * batchSize, (b + 1) * batchSize);\n\t\t\t\t\tconst batch = Object.fromEntries(batchKeys.map((k) => [k, data[k]]));\n\t\t\t\t\treturn { batch, batchKeys };\n\t\t\t\t},\n\t\t\t);\n\n\t\t\tconst results = await Promise.allSettled(\n\t\t\t\tbatches.map(({ batch, batchKeys }) =>\n\t\t\t\t\tthis.translateBatch(batch, options, batchKeys),\n\t\t\t\t),\n\t\t\t);\n\n\t\t\tfor (let b = 0; b < results.length; b++) {\n\t\t\t\tconst result = results[b];\n\t\t\t\tif (result.status !== \"fulfilled\") {\n\t\t\t\t\tconsole.error(\n\t\t\t\t\t\t`[rosetta] batch failed (${batches[b].batchKeys.length} keys):`,\n\t\t\t\t\t\tresult.reason?.message?.slice(0, 120),\n\t\t\t\t\t);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tObject.assign(output, result.value);\n\t\t\t}\n\t\t}\n\n\t\treturn output;\n\t}\n\n\tprivate async translateBatch(\n\t\tbatch: Record<string, unknown>,\n\t\toptions: TranslateDataOptions,\n\t\tbatchKeys: string[],\n\t): Promise<Record<string, unknown>> {\n\t\tconst retries = this.config.retries ?? 2;\n\t\tconst system = buildSystemPrompt({\n\t\t\tbrandVoice: this.config.brandVoice,\n\t\t\tglossary: this.config.glossary,\n\t\t\tsource: options.source,\n\t\t\ttarget: options.target,\n\t\t});\n\n\t\tconst user = buildDataPrompt(batch, {\n\t\t\t...options,\n\t\t\thints: options.hints\n\t\t\t\t? Object.fromEntries(\n\t\t\t\t\t\tbatchKeys.map((key) => [key, options.hints?.[key] ?? []]),\n\t\t\t\t\t)\n\t\t\t\t: undefined,\n\t\t});\n\n\t\tlet lastError: Error | undefined;\n\t\tfor (let attempt = 0; attempt <= retries; attempt++) {\n\t\t\ttry {\n\t\t\t\tconst res = await this.chat([\n\t\t\t\t\t{ role: \"system\", content: system },\n\t\t\t\t\t{ role: \"user\", content: user },\n\t\t\t\t]);\n\t\t\t\tif (!res.ok) {\n\t\t\t\t\tthrow new Error(`Rosetta: ${res.status} ${await res.text()}`);\n\t\t\t\t}\n\t\t\t\tconst json = (await res.json()) as {\n\t\t\t\t\tchoices: Array<{ message: { content: string } }>;\n\t\t\t\t};\n\t\t\t\treturn JSON.parse(json.choices[0].message.content);\n\t\t\t} catch (error) {\n\t\t\t\tlastError = error instanceof Error ? error : new Error(String(error));\n\t\t\t\tif (attempt < retries) {\n\t\t\t\t\tawait new Promise((ok) => setTimeout(ok, 2000 * (attempt + 1)));\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tthrow lastError ?? new Error(\"Rosetta: batch failed\");\n\t}\n\n\tprivate async chat(messages: ChatMessage[]): Promise<Response> {\n\t\tconst baseURL = this.config.baseURL ?? \"https://openrouter.ai/api/v1\";\n\t\treturn fetch(`${baseURL}/chat/completions`, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: {\n\t\t\t\tAuthorization: `Bearer ${this.config.apiKey}`,\n\t\t\t\t\"Content-Type\": \"application/json\",\n\t\t\t},\n\t\t\tbody: JSON.stringify({\n\t\t\t\tmodel: this.config.model,\n\t\t\t\ttemperature: this.config.temperature ?? 0.3,\n\t\t\t\tmessages,\n\t\t\t}),\n\t\t});\n\t}\n}\n"],"names":[],"mappings":"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"}

package/dist/types/config.d.ts

@@ -0,0 +1,42 @@
+export interface BrandVoice {
+    /**
+     * Free-form briefing: tone, formality, audience, conventions. One text per
+     * target locale; `*` is the fallback for locales without their own text.
+     */
+    variations: Record<string, string>;
+}
+export type Glossary = Record<string, Record<string, string>>;
+export interface RosettaConfig {
+    /** API key for the OpenAI-compatible endpoint. */
+    apiKey: string;
+    /** Model id (e.g. `anthropic/claude-sonnet-4.5` via OpenRouter). */
+    model: string;
+    /** OpenAI-compatible chat completions endpoint. */
+    baseURL?: string;
+    /** Brand voice: tone + conventions per locale. */
+    brandVoice: BrandVoice;
+    /** Exact term mappings per locale — highest precedence. */
+    glossary?: Glossary;
+    /** Sampling temperature (default 0.3 for translation consistency). */
+    temperature?: number;
+    /** Keys per LLM request when translating large payloads. */
+    batchSize?: number;
+    /** Parallel batch requests in flight. */
+    concurrency?: number;
+    /** Retries per batch on failure. */
+    retries?: number;
+}
+export interface TranslateDataOptions {
+    source: string;
+    target: string;
+    /** Broad context: product surface, audience, purpose. */
+    context?: string;
+    /** Per-key hints that disambiguate short or overloaded text. */
+    hints?: Record<string, string[]>;
+}
+export interface TranslateTextOptions {
+    source: string;
+    target: string;
+    /** Broad context for this translation. */
+    context?: string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,28 @@
+import type { RosettaConfig, TranslateDataOptions, TranslateTextOptions } from "./config";
+export type { RosettaConfig, TranslateDataOptions, TranslateTextOptions, } from "./config";
+/**
+ * Rosetta — self-hosted AI translation engine.
+ *
+ * Translates key-value content across locales through any OpenAI-compatible
+ * LLM, with brand voice, glossary, and per-locale rules applied on every
+ * call. Works with OpenRouter, direct Anthropic/OpenAI, or any
+ * OpenAI-compatible endpoint.
+ *
+ * Non-throwing at the batch level: failed batches are logged and skipped, so
+ * partial translations degrade gracefully to the source locale.
+ */
+export declare class Rosetta {
+    private config;
+    constructor(config: RosettaConfig);
+    /** Translate a single text string. */
+    translateText(text: string, options: TranslateTextOptions): Promise<string>;
+    /**
+     * Translate a key-value payload, batched with concurrency. Failed batches
+     * are logged and skipped — the returned object carries only successfully
+     * translated keys, letting the caller fall back to the source locale for
+     * the rest.
+     */
+    translate(data: Record<string, unknown>, options: TranslateDataOptions): Promise<Record<string, unknown>>;
+    private translateBatch;
+    private chat;
+}

package/dist/types/prompt.d.ts

@@ -0,0 +1,17 @@
+import type { BrandVoice, Glossary, TranslateDataOptions } from "./config";
+/**
+ * Builds the system prompt for a translation request: brand voice, glossary
+ * enforcement, locale conventions, and output-shape rules.
+ */
+export declare function buildSystemPrompt(options: {
+    brandVoice: BrandVoice;
+    glossary?: Glossary;
+    source: string;
+    target: string;
+}): string;
+/**
+ * Builds the user prompt for a key-value payload translation.
+ */
+export declare function buildDataPrompt(data: Record<string, unknown>, options: TranslateDataOptions & {
+    hints?: Record<string, string[]>;
+}): string;

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "rosetta-i18n",
+	"version": "0.1.0",
+	"author": "Ian Hunter <ian@01.studio>",
+	"license": "MIT",
+	"description": "Self-hosted AI translation engine — translate key-value content across locales through any OpenAI-compatible LLM, with brand voice and glossary enforcement.",
+	"homepage": "https://github.com/ian/rosetta#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ian/rosetta.git"
+	},
+	"bugs": {
+		"url": "https://github.com/ian/rosetta/issues"
+	},
+	"keywords": [
+		"translation",
+		"i18n",
+		"localization",
+		"llm",
+		"ai",
+		"openai",
+		"openrouter",
+		"rosetta-i18n"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"main": "./dist/esm/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"default": "./dist/esm/index.js"
+		},
+		"./config": {
+			"types": "./dist/types/config.d.ts",
+			"default": "./dist/esm/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"clean": "rm -rf ./dist",
+		"build": "rollup -c && tsc -p tsconfig.build.json",
+		"build:watch": "rollup -c -w",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"bump": "./scripts/bump",
+		"release": "./scripts/release",
+		"format": "biome format",
+		"format:fix": "biome format --write",
+		"lint": "biome check",
+		"lint:fix": "biome check --write"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.12",
+		"@types/node": "22.15.3",
+		"rollup": "^4.63.1",
+		"rollup-plugin-esbuild": "^6.1.1",
+		"typescript": "5.9.2",
+		"vitest": "^3.2.7"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"packageManager": "pnpm@9.7.1"
+}