canopy-i18n 0.8.2 → 0.9.0

package/README.md

@@ -226,6 +226,141 @@ const {
 - `createI18nReact` itself has no built-in persistence. Use a built-in wrapper (`createHash/Search/Pathname/Storage/CookieI18nReact`) for common sources, or pass your own `useLocaleSource` / `onLocaleChange` for anything else.
 - React is a `peerDependency` (`>=18`). Non-React users can ignore the `/react` subpath entirely.
 
+## AI Translation
+
+The `canopy-i18n/ai` subpath provides a runtime translator built around a pluggable adapter. Bring any AI backend by implementing a single `translate` function.
+
+```ts
+import { createAITranslator, memoryCache } from 'canopy-i18n/ai';
+
+const translator = createAITranslator({
+  // Implement AIAdapter with any provider (OpenAI, local model, ...)
+  adapter: {
+    async translate({ texts, from, to }) {
+      const translated = await callYourAI(texts, from, to);
+      return translated; // same order and length as texts
+    },
+  },
+  sourceLocale: 'ja',
+  cache: memoryCache(), // optional; implement TranslationCache for DB persistence
+});
+```
+
+### Built-in adapters
+
+Ready-made adapters for OpenAI, Anthropic (Claude), and Google Gemini. All are fetch-based with no SDK dependency. `model` and `apiKey` are required; `instructions` and `baseURL` are optional.
+
+```ts
+import {
+  createAITranslator,
+  memoryCache,
+  openAIAdapter,
+  anthropicAdapter,
+  geminiAdapter,
+} from 'canopy-i18n/ai';
+
+const adapter = openAIAdapter({
+  model: 'gpt-4o-mini',
+  apiKey: process.env.OPENAI_API_KEY!,
+  // baseURL: 'http://localhost:11434/v1', // any OpenAI-compatible API (Ollama, etc.)
+  // instructions: 'Do not translate the product name "Canopy".',
+});
+
+// or
+anthropicAdapter({
+  model: 'claude-haiku-4-5',
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  // maxTokens: 8192, // the Anthropic API requires max_tokens; this is the default
+});
+
+// or
+geminiAdapter({
+  model: 'gemini-2.0-flash',
+  apiKey: process.env.GEMINI_API_KEY!,
+});
+
+const translator = createAITranslator({
+  adapter,
+  sourceLocale: 'ja',
+  cache: memoryCache(),
+});
+```
+
+### Prompt helpers
+
+The prompt logic used by the built-in adapter is exported, so custom adapters can reuse it instead of writing their own:
+
+```ts
+import { buildTranslatePrompt, parseTranslatedTexts } from 'canopy-i18n/ai';
+
+const adapter = {
+  async translate(request) {
+    const prompt = buildTranslatePrompt(request, { instructions: 'Keep it casual.' });
+    const raw = await callYourAI(prompt);
+    // strips code fences / surrounding text, validates order & length
+    return parseTranslatedTexts(raw, request.texts.length);
+  },
+};
+```
+
+### Translating dynamic texts (e.g. user input)
+
+```ts
+const translated = await translator.translate(userComment, { to: 'en' });
+const many = await translator.translateMany(['こんにちは', 'さようなら'], { to: 'en' });
+
+// Source language unknown? Omit both sourceLocale and `from` —
+// the adapter receives `from: undefined` and should auto-detect.
+const detected = await translator.translate(anyLanguageInput, { to: 'ja' });
+```
+
+- `from` falls back to `sourceLocale`; if neither is set, the adapter auto-detects.
+- Results are cached (`cache` option), so the same text is translated only once.
+- Concurrent requests for the same text are deduplicated into a single adapter call.
+- `translateMany` batches all texts into one adapter call.
+- On adapter failure the original text is returned by default (`onError: 'fallback'`). Set `onError: 'throw'` to propagate errors.
+
+### Completing message entries
+
+Write only the source locale and let AI fill in the rest. The result is a complete entries object for `ChainBuilder.add()`:
+
+```ts
+const entries = await translator.completeEntries(['ja', 'en', 'fr'] as const, {
+  title: { ja: 'タイトル' },                      // en & fr are AI-translated
+  greeting: { ja: 'こんにちは', en: 'Hello' },     // existing en is kept, fr is AI-translated
+});
+
+const messages = createI18n(['ja', 'en', 'fr'] as const)
+  .add(entries)
+  .build('en');
+```
+
+Only static string entries are supported; template functions are out of scope for AI translation.
+
+### Interfaces
+
+```ts
+interface AIAdapter {
+  // `from` is undefined when the source language is unknown — auto-detect it
+  translate(request: { texts: string[]; from?: string; to: string }): Promise<string[]>;
+}
+
+interface TranslationCache {
+  get(key: string): Promise<string | undefined> | string | undefined;
+  set(key: string, value: string): Promise<void> | void;
+}
+```
+
+```ts
+createAITranslator({
+  adapter,             // AIAdapter (required)
+  sourceLocale: 'ja',  // default `from` (optional; required for completeEntries)
+  cache,               // TranslationCache (optional)
+  onError: 'fallback', // 'fallback' (default) | 'throw'
+  cacheKey,            // (text, from, to) => string (optional)
+});
+```
+
 ## API
 
 ### `createI18n(locales)`

package/dist/adaptors/ai/anthropic.d.ts

@@ -0,0 +1,19 @@
+import type { TranslatePromptOptions } from "./prompt.js";
+import type { AIAdapter } from "./types.js";
+export interface AnthropicAdapterOptions extends TranslatePromptOptions {
+    /** Model name, e.g. "claude-haiku-4-5". Required: model lineups change too often to default. */
+    model: string;
+    /** API key. */
+    apiKey: string;
+    /** Max output tokens (the Anthropic API requires this). Defaults to 8192. */
+    maxTokens?: number;
+    /** Defaults to "https://api.anthropic.com/v1". */
+    baseURL?: string;
+    /** Custom fetch implementation (testing, proxies). Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Built-in adapter for the Anthropic (Claude) Messages API.
+ * Uses fetch directly — no SDK dependency.
+ */
+export declare function anthropicAdapter(options: AnthropicAdapterOptions): AIAdapter;

package/dist/adaptors/ai/anthropic.js

@@ -0,0 +1,36 @@
+import { buildTranslatePrompt, parseTranslatedTexts } from "./prompt.js";
+/**
+ * Built-in adapter for the Anthropic (Claude) Messages API.
+ * Uses fetch directly — no SDK dependency.
+ */
+export function anthropicAdapter(options) {
+    const baseURL = (options.baseURL ?? "https://api.anthropic.com/v1").replace(/\/+$/, "");
+    const fetchFn = options.fetch ?? fetch;
+    return {
+        async translate(request) {
+            const res = await fetchFn(`${baseURL}/messages`, {
+                method: "POST",
+                headers: {
+                    "x-api-key": options.apiKey,
+                    "anthropic-version": "2023-06-01",
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: options.model,
+                    max_tokens: options.maxTokens ?? 8192,
+                    messages: [{ role: "user", content: buildTranslatePrompt(request, options) }],
+                }),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new Error(`Anthropic API error ${res.status}: ${body}`);
+            }
+            const json = (await res.json());
+            const text = json.content?.find((block) => block.type === "text")?.text;
+            if (typeof text !== "string") {
+                throw new Error("Anthropic API returned no text content");
+            }
+            return parseTranslatedTexts(text, request.texts.length);
+        },
+    };
+}

package/dist/adaptors/ai/anthropic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adaptors/ai/anthropic.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { anthropicAdapter } from "./anthropic.js";
+function fakeFetch(handler) {
+    const requests = [];
+    const fetchFn = (async (input, init) => {
+        const url = String(input);
+        requests.push({ url, init });
+        return handler(url, init);
+    });
+    return { fetchFn, requests };
+}
+function messagesResponse(text) {
+    return new Response(JSON.stringify({ content: [{ type: "text", text }] }), {
+        status: 200,
+    });
+}
+describe("anthropicAdapter", () => {
+    it("calls the Messages API and parses the result", async () => {
+        const { fetchFn, requests } = fakeFetch(() => messagesResponse('["Hello"]'));
+        const adapter = anthropicAdapter({
+            model: "test-model",
+            apiKey: "sk-ant-test",
+            fetch: fetchFn,
+        });
+        const result = await adapter.translate({ texts: ["こんにちは"], from: "ja", to: "en" });
+        expect(result).toEqual(["Hello"]);
+        expect(requests[0]?.url).toBe("https://api.anthropic.com/v1/messages");
+        const headers = requests[0]?.init?.headers;
+        expect(headers["x-api-key"]).toBe("sk-ant-test");
+        expect(headers["anthropic-version"]).toBe("2023-06-01");
+        const body = JSON.parse(requests[0]?.init?.body);
+        expect(body.model).toBe("test-model");
+        expect(body.max_tokens).toBe(8192);
+        expect(body.messages[0].content).toContain('from "ja" to "en"');
+    });
+    it("respects maxTokens and baseURL", async () => {
+        const { fetchFn, requests } = fakeFetch(() => messagesResponse('["Hello"]'));
+        const adapter = anthropicAdapter({
+            model: "test-model",
+            apiKey: "sk-ant-test",
+            maxTokens: 1024,
+            baseURL: "http://localhost:8080/v1/",
+            fetch: fetchFn,
+        });
+        await adapter.translate({ texts: ["a"], from: "ja", to: "en" });
+        expect(requests[0]?.url).toBe("http://localhost:8080/v1/messages");
+        expect(JSON.parse(requests[0]?.init?.body).max_tokens).toBe(1024);
+    });
+    it("throws with status and body on API errors", async () => {
+        const { fetchFn } = fakeFetch(() => new Response("overloaded", { status: 529 }));
+        const adapter = anthropicAdapter({
+            model: "test-model",
+            apiKey: "sk-ant-test",
+            fetch: fetchFn,
+        });
+        await expect(adapter.translate({ texts: ["a"], from: "ja", to: "en" })).rejects.toThrow("Anthropic API error 529: overloaded");
+    });
+    it("throws when the response has no text content", async () => {
+        const { fetchFn } = fakeFetch(() => new Response(JSON.stringify({ content: [] }), { status: 200 }));
+        const adapter = anthropicAdapter({
+            model: "test-model",
+            apiKey: "sk-ant-test",
+            fetch: fetchFn,
+        });
+        await expect(adapter.translate({ texts: ["a"], from: "ja", to: "en" })).rejects.toThrow("no text content");
+    });
+});

package/dist/adaptors/ai/cache.d.ts

@@ -0,0 +1,5 @@
+import type { TranslationCache } from "./types.js";
+/**
+ * Built-in in-memory cache. For persistence, implement TranslationCache yourself.
+ */
+export declare function memoryCache(): TranslationCache;

package/dist/adaptors/ai/cache.js

@@ -0,0 +1,12 @@
+/**
+ * Built-in in-memory cache. For persistence, implement TranslationCache yourself.
+ */
+export function memoryCache() {
+    const store = new Map();
+    return {
+        get: (key) => store.get(key),
+        set: (key, value) => {
+            store.set(key, value);
+        },
+    };
+}

package/dist/adaptors/ai/gemini.d.ts

@@ -0,0 +1,17 @@
+import type { TranslatePromptOptions } from "./prompt.js";
+import type { AIAdapter } from "./types.js";
+export interface GeminiAdapterOptions extends TranslatePromptOptions {
+    /** Model name, e.g. "gemini-2.0-flash". Required: model lineups change too often to default. */
+    model: string;
+    /** API key. */
+    apiKey: string;
+    /** Defaults to "https://generativelanguage.googleapis.com/v1beta". */
+    baseURL?: string;
+    /** Custom fetch implementation (testing, proxies). Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Built-in adapter for the Google Gemini API (generateContent).
+ * Uses fetch directly — no SDK dependency.
+ */
+export declare function geminiAdapter(options: GeminiAdapterOptions): AIAdapter;

package/dist/adaptors/ai/gemini.js

@@ -0,0 +1,35 @@
+import { buildTranslatePrompt, parseTranslatedTexts } from "./prompt.js";
+/**
+ * Built-in adapter for the Google Gemini API (generateContent).
+ * Uses fetch directly — no SDK dependency.
+ */
+export function geminiAdapter(options) {
+    const baseURL = (options.baseURL ?? "https://generativelanguage.googleapis.com/v1beta").replace(/\/+$/, "");
+    const fetchFn = options.fetch ?? fetch;
+    return {
+        async translate(request) {
+            const res = await fetchFn(`${baseURL}/models/${options.model}:generateContent`, {
+                method: "POST",
+                headers: {
+                    "x-goog-api-key": options.apiKey,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    contents: [{ parts: [{ text: buildTranslatePrompt(request, options) }] }],
+                }),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new Error(`Gemini API error ${res.status}: ${body}`);
+            }
+            const json = (await res.json());
+            const text = json.candidates?.[0]?.content?.parts
+                ?.map((part) => part.text ?? "")
+                .join("");
+            if (!text) {
+                throw new Error("Gemini API returned no text content");
+            }
+            return parseTranslatedTexts(text, request.texts.length);
+        },
+    };
+}

package/dist/adaptors/ai/gemini.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adaptors/ai/gemini.test.js

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { geminiAdapter } from "./gemini.js";
+function fakeFetch(handler) {
+    const requests = [];
+    const fetchFn = (async (input, init) => {
+        const url = String(input);
+        requests.push({ url, init });
+        return handler(url, init);
+    });
+    return { fetchFn, requests };
+}
+function generateContentResponse(text) {
+    return new Response(JSON.stringify({ candidates: [{ content: { parts: [{ text }] } }] }), { status: 200 });
+}
+describe("geminiAdapter", () => {
+    it("calls the generateContent API and parses the result", async () => {
+        const { fetchFn, requests } = fakeFetch(() => generateContentResponse('["Hello"]'));
+        const adapter = geminiAdapter({
+            model: "test-model",
+            apiKey: "AIza-test",
+            fetch: fetchFn,
+        });
+        const result = await adapter.translate({ texts: ["こんにちは"], from: "ja", to: "en" });
+        expect(result).toEqual(["Hello"]);
+        expect(requests[0]?.url).toBe("https://generativelanguage.googleapis.com/v1beta/models/test-model:generateContent");
+        const headers = requests[0]?.init?.headers;
+        expect(headers["x-goog-api-key"]).toBe("AIza-test");
+        const body = JSON.parse(requests[0]?.init?.body);
+        expect(body.contents[0].parts[0].text).toContain('from "ja" to "en"');
+    });
+    it("joins multiple response parts", async () => {
+        const { fetchFn } = fakeFetch(() => new Response(JSON.stringify({
+            candidates: [{ content: { parts: [{ text: '["Hel' }, { text: 'lo"]' }] } }],
+        }), { status: 200 }));
+        const adapter = geminiAdapter({
+            model: "test-model",
+            apiKey: "AIza-test",
+            fetch: fetchFn,
+        });
+        const result = await adapter.translate({ texts: ["a"], from: "ja", to: "en" });
+        expect(result).toEqual(["Hello"]);
+    });
+    it("respects a custom baseURL", async () => {
+        const { fetchFn, requests } = fakeFetch(() => generateContentResponse('["Hello"]'));
+        const adapter = geminiAdapter({
+            model: "test-model",
+            apiKey: "AIza-test",
+            baseURL: "http://localhost:8080/v1beta/",
+            fetch: fetchFn,
+        });
+        await adapter.translate({ texts: ["a"], from: "ja", to: "en" });
+        expect(requests[0]?.url).toBe("http://localhost:8080/v1beta/models/test-model:generateContent");
+    });
+    it("throws with status and body on API errors", async () => {
+        const { fetchFn } = fakeFetch(() => new Response("quota exceeded", { status: 429 }));
+        const adapter = geminiAdapter({
+            model: "test-model",
+            apiKey: "AIza-test",
+            fetch: fetchFn,
+        });
+        await expect(adapter.translate({ texts: ["a"], from: "ja", to: "en" })).rejects.toThrow("Gemini API error 429: quota exceeded");
+    });
+    it("throws when the response has no text content", async () => {
+        const { fetchFn } = fakeFetch(() => new Response(JSON.stringify({ candidates: [] }), { status: 200 }));
+        const adapter = geminiAdapter({
+            model: "test-model",
+            apiKey: "AIza-test",
+            fetch: fetchFn,
+        });
+        await expect(adapter.translate({ texts: ["a"], from: "ja", to: "en" })).rejects.toThrow("no text content");
+    });
+});

package/dist/adaptors/ai/index.d.ts

@@ -0,0 +1,12 @@
+export { anthropicAdapter } from "./anthropic.js";
+export type { AnthropicAdapterOptions } from "./anthropic.js";
+export { memoryCache } from "./cache.js";
+export { geminiAdapter } from "./gemini.js";
+export type { GeminiAdapterOptions } from "./gemini.js";
+export { openAIAdapter } from "./openai.js";
+export type { OpenAIAdapterOptions } from "./openai.js";
+export { buildTranslatePrompt, parseTranslatedTexts } from "./prompt.js";
+export type { TranslatePromptOptions } from "./prompt.js";
+export { AITranslator, createAITranslator } from "./translator.js";
+export type { AITranslatorOptions, TranslateOptions } from "./translator.js";
+export type { AIAdapter, AITranslateRequest, TranslationCache } from "./types.js";

package/dist/adaptors/ai/index.js

@@ -0,0 +1,6 @@
+export { anthropicAdapter } from "./anthropic.js";
+export { memoryCache } from "./cache.js";
+export { geminiAdapter } from "./gemini.js";
+export { openAIAdapter } from "./openai.js";
+export { buildTranslatePrompt, parseTranslatedTexts } from "./prompt.js";
+export { AITranslator, createAITranslator } from "./translator.js";

package/dist/adaptors/ai/openai.d.ts

@@ -0,0 +1,17 @@
+import type { TranslatePromptOptions } from "./prompt.js";
+import type { AIAdapter } from "./types.js";
+export interface OpenAIAdapterOptions extends TranslatePromptOptions {
+    /** Model name, e.g. "gpt-4o-mini". Required: model lineups change too often to default. */
+    model: string;
+    /** API key. */
+    apiKey: string;
+    /** Defaults to "https://api.openai.com/v1". Point this at any OpenAI-compatible API. */
+    baseURL?: string;
+    /** Custom fetch implementation (testing, proxies). Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Built-in adapter for the OpenAI Chat Completions API (and compatible APIs).
+ * Uses fetch directly — no SDK dependency.
+ */
+export declare function openAIAdapter(options: OpenAIAdapterOptions): AIAdapter;

package/dist/adaptors/ai/openai.js

@@ -0,0 +1,35 @@
+import { buildTranslatePrompt, parseTranslatedTexts } from "./prompt.js";
+/**
+ * Built-in adapter for the OpenAI Chat Completions API (and compatible APIs).
+ * Uses fetch directly — no SDK dependency.
+ */
+export function openAIAdapter(options) {
+    const baseURL = (options.baseURL ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+    const fetchFn = options.fetch ?? fetch;
+    return {
+        async translate(request) {
+            const { apiKey } = options;
+            const res = await fetchFn(`${baseURL}/chat/completions`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: options.model,
+                    messages: [{ role: "user", content: buildTranslatePrompt(request, options) }],
+                }),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new Error(`OpenAI API error ${res.status}: ${body}`);
+            }
+            const json = (await res.json());
+            const content = json.choices?.[0]?.message?.content;
+            if (typeof content !== "string") {
+                throw new Error("OpenAI API returned no message content");
+            }
+            return parseTranslatedTexts(content, request.texts.length);
+        },
+    };
+}

package/dist/adaptors/ai/openai.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adaptors/ai/openai.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { openAIAdapter } from "./openai.js";
+function fakeFetch(handler) {
+    const requests = [];
+    const fetchFn = (async (input, init) => {
+        const url = String(input);
+        requests.push({ url, init });
+        return handler(url, init);
+    });
+    return { fetchFn, requests };
+}
+function chatResponse(content) {
+    return new Response(JSON.stringify({ choices: [{ message: { content } }] }), {
+        status: 200,
+    });
+}
+describe("openAIAdapter", () => {
+    it("calls the Chat Completions API and parses the result", async () => {
+        const { fetchFn, requests } = fakeFetch(() => chatResponse('["Hello"]'));
+        const adapter = openAIAdapter({ model: "test-model", apiKey: "sk-test", fetch: fetchFn });
+        const result = await adapter.translate({ texts: ["こんにちは"], from: "ja", to: "en" });
+        expect(result).toEqual(["Hello"]);
+        expect(requests).toHaveLength(1);
+        expect(requests[0]?.url).toBe("https://api.openai.com/v1/chat/completions");
+        const init = requests[0]?.init;
+        expect((init?.headers).Authorization).toBe("Bearer sk-test");
+        const body = JSON.parse(init?.body);
+        expect(body.model).toBe("test-model");
+        expect(body.messages[0].content).toContain('from "ja" to "en"');
+        expect(body.messages[0].content).toContain('["こんにちは"]');
+    });
+    it("respects a custom baseURL (OpenAI-compatible APIs)", async () => {
+        const { fetchFn, requests } = fakeFetch(() => chatResponse('["Hello"]'));
+        const adapter = openAIAdapter({
+            model: "local-model",
+            apiKey: "sk-test",
+            baseURL: "http://localhost:11434/v1/",
+            fetch: fetchFn,
+        });
+        await adapter.translate({ texts: ["a"], from: "ja", to: "en" });
+        expect(requests[0]?.url).toBe("http://localhost:11434/v1/chat/completions");
+    });
+    it("passes instructions into the prompt", async () => {
+        const { fetchFn, requests } = fakeFetch(() => chatResponse('["Hello"]'));
+        const adapter = openAIAdapter({
+            model: "test-model",
+            apiKey: "sk-test",
+            instructions: "Keep it casual.",
+            fetch: fetchFn,
+        });
+        await adapter.translate({ texts: ["a"], from: "ja", to: "en" });
+        const body = JSON.parse(requests[0]?.init?.body);
+        expect(body.messages[0].content).toContain("Keep it casual.");
+    });
+    it("throws with status and body on API errors", async () => {
+        const { fetchFn } = fakeFetch(() => new Response("rate limited", { status: 429 }));
+        const adapter = openAIAdapter({ model: "test-model", apiKey: "sk-test", fetch: fetchFn });
+        await expect(adapter.translate({ texts: ["a"], from: "ja", to: "en" })).rejects.toThrow("OpenAI API error 429: rate limited");
+    });
+    it("throws when the response has no message content", async () => {
+        const { fetchFn } = fakeFetch(() => new Response(JSON.stringify({ choices: [] }), { status: 200 }));
+        const adapter = openAIAdapter({ model: "test-model", apiKey: "sk-test", fetch: fetchFn });
+        await expect(adapter.translate({ texts: ["a"], from: "ja", to: "en" })).rejects.toThrow("no message content");
+    });
+});

package/dist/adaptors/ai/prompt.d.ts

@@ -0,0 +1,15 @@
+import type { AITranslateRequest } from "./types.js";
+export interface TranslatePromptOptions {
+    /** Extra instructions appended to the prompt (tone, glossary, terms to keep, ...) */
+    instructions?: string;
+}
+/**
+ * Build a provider-neutral translation prompt.
+ * Built-in adapters use this; custom adapters can too.
+ */
+export declare function buildTranslatePrompt(request: AITranslateRequest, options?: TranslatePromptOptions): string;
+/**
+ * Parse an AI response into translated texts.
+ * Tolerates code fences and surrounding text, and validates the result.
+ */
+export declare function parseTranslatedTexts(raw: string, expected: number): string[];

package/dist/adaptors/ai/prompt.js

@@ -0,0 +1,47 @@
+/**
+ * Build a provider-neutral translation prompt.
+ * Built-in adapters use this; custom adapters can too.
+ */
+export function buildTranslatePrompt(request, options = {}) {
+    const { texts, from, to } = request;
+    const lines = [
+        from === undefined
+            ? `Detect the language of each text and translate it to "${to}".`
+            : `Translate each text from "${from}" to "${to}".`,
+        "Rules:",
+        "- Return ONLY a JSON array of strings, in the same order and length as the input.",
+        "- Do not add explanations, code fences, or any text outside the JSON array.",
+        "- Keep placeholders (e.g. {name}), code, URLs, and proper nouns as they are.",
+        "- Preserve the tone and formatting of each text.",
+    ];
+    if (options.instructions) {
+        lines.push(`Additional instructions: ${options.instructions}`);
+    }
+    lines.push("", "Input:", JSON.stringify(texts));
+    return lines.join("\n");
+}
+/**
+ * Parse an AI response into translated texts.
+ * Tolerates code fences and surrounding text, and validates the result.
+ */
+export function parseTranslatedTexts(raw, expected) {
+    const start = raw.indexOf("[");
+    const end = raw.lastIndexOf("]");
+    if (start === -1 || end < start) {
+        throw new Error("AI response does not contain a JSON array");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.slice(start, end + 1));
+    }
+    catch {
+        throw new Error("AI response contains an invalid JSON array");
+    }
+    if (!Array.isArray(parsed) || !parsed.every((v) => typeof v === "string")) {
+        throw new Error("AI response is not a JSON array of strings");
+    }
+    if (parsed.length !== expected) {
+        throw new Error(`AI returned ${parsed.length} texts, expected ${expected}`);
+    }
+    return parsed;
+}

package/dist/adaptors/ai/prompt.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adaptors/ai/prompt.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { buildTranslatePrompt, parseTranslatedTexts } from "./prompt.js";
+describe("buildTranslatePrompt", () => {
+    it("includes from, to and the texts as JSON", () => {
+        const prompt = buildTranslatePrompt({ texts: ["こんにちは"], from: "ja", to: "en" });
+        expect(prompt).toContain('from "ja" to "en"');
+        expect(prompt).toContain('["こんにちは"]');
+    });
+    it("asks for language detection when from is omitted", () => {
+        const prompt = buildTranslatePrompt({ texts: ["hola"], to: "ja" });
+        expect(prompt).toContain("Detect the language");
+        expect(prompt).toContain('to "ja"');
+    });
+    it("appends custom instructions", () => {
+        const prompt = buildTranslatePrompt({ texts: ["a"], from: "ja", to: "en" }, { instructions: 'Do not translate "Canopy".' });
+        expect(prompt).toContain('Additional instructions: Do not translate "Canopy".');
+    });
+});
+describe("parseTranslatedTexts", () => {
+    it("parses a plain JSON array", () => {
+        expect(parseTranslatedTexts('["Hello", "Goodbye"]', 2)).toEqual(["Hello", "Goodbye"]);
+    });
+    it("tolerates code fences and surrounding text", () => {
+        const raw = 'Here is the translation:\n```json\n["Hello"]\n```\n';
+        expect(parseTranslatedTexts(raw, 1)).toEqual(["Hello"]);
+    });
+    it("throws when no JSON array is found", () => {
+        expect(() => parseTranslatedTexts("sorry, I cannot do that", 1)).toThrow("does not contain a JSON array");
+    });
+    it("throws on a length mismatch", () => {
+        expect(() => parseTranslatedTexts('["a"]', 2)).toThrow("expected 2");
+    });
+    it("throws when items are not strings", () => {
+        expect(() => parseTranslatedTexts("[1, 2]", 2)).toThrow("not a JSON array of strings");
+    });
+});

package/dist/adaptors/ai/translator.d.ts

@@ -0,0 +1,53 @@
+import type { AIAdapter, TranslationCache } from "./types.js";
+export interface AITranslatorOptions<S extends string = string> {
+    /** Translation backend. Implement AIAdapter to use any provider. */
+    adapter: AIAdapter;
+    /**
+     * Default locale of the original texts, used when `from` is omitted.
+     * When neither is given, the adapter receives `from: undefined` and
+     * should detect the source language (required for completeEntries).
+     */
+    sourceLocale?: S;
+    /** Optional cache to avoid repeated adapter calls. */
+    cache?: TranslationCache;
+    /**
+     * What to do when the adapter fails.
+     * - "fallback" (default): return the original text
+     * - "throw": rethrow the error
+     */
+    onError?: "fallback" | "throw";
+    /** Customize cache keys. Default: `${from ?? "auto"}:${to}:${text}` */
+    cacheKey?: (text: string, from: string | undefined, to: string) => string;
+}
+export interface TranslateOptions {
+    to: string;
+    from?: string;
+}
+export declare class AITranslator<S extends string = string> {
+    private readonly adapter;
+    private readonly sourceLocale?;
+    private readonly cache?;
+    private readonly onError;
+    private readonly makeKey;
+    /** Deduplicates concurrent requests for the same text */
+    private readonly inflight;
+    constructor(options: AITranslatorOptions<S>);
+    /**
+     * Translate a single text (e.g. user input) at runtime.
+     */
+    translate(text: string, options: TranslateOptions): Promise<string>;
+    /**
+     * Translate multiple texts in a single adapter call.
+     * Results are cached and concurrent requests for the same text are deduplicated.
+     */
+    translateMany(texts: string[], options: TranslateOptions): Promise<string[]>;
+    /**
+     * Fill in missing locales of static message entries.
+     * Existing translations are kept; only missing ones are translated
+     * from the source locale. The result can be passed to ChainBuilder.add().
+     */
+    completeEntries<const Ls extends readonly string[], E extends Record<string, Partial<Record<Ls[number], string>> & Record<S, string>>>(locales: Ls, entries: E): Promise<{
+        [K in keyof E]: Record<Ls[number], string>;
+    }>;
+}
+export declare function createAITranslator<S extends string = string>(options: AITranslatorOptions<S>): AITranslator<S>;

package/dist/adaptors/ai/translator.js

@@ -0,0 +1,153 @@
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    promise.catch(() => { }); // avoid unhandled rejection
+    return { promise, resolve, reject };
+}
+export class AITranslator {
+    adapter;
+    sourceLocale;
+    cache;
+    onError;
+    makeKey;
+    /** Deduplicates concurrent requests for the same text */
+    inflight = new Map();
+    constructor(options) {
+        this.adapter = options.adapter;
+        this.sourceLocale = options.sourceLocale;
+        this.cache = options.cache;
+        this.onError = options.onError ?? "fallback";
+        this.makeKey = options.cacheKey ?? ((text, from, to) => `${from ?? "auto"}:${to}:${text}`);
+    }
+    /**
+     * Translate a single text (e.g. user input) at runtime.
+     */
+    async translate(text, options) {
+        const results = await this.translateMany([text], options);
+        return results[0];
+    }
+    /**
+     * Translate multiple texts in a single adapter call.
+     * Results are cached and concurrent requests for the same text are deduplicated.
+     */
+    async translateMany(texts, options) {
+        const from = options.from ?? this.sourceLocale;
+        const to = options.to;
+        if (from !== undefined && from === to)
+            return [...texts];
+        const keys = texts.map((text) => this.makeKey(text, from, to));
+        const textByKey = new Map();
+        // Keys this call resolves itself vs. keys another call is already resolving.
+        // Claim ownership synchronously so concurrent calls dedup reliably.
+        const owned = new Map();
+        const waiting = new Map();
+        for (const [i, key] of keys.entries()) {
+            if (textByKey.has(key))
+                continue;
+            const text = texts[i];
+            textByKey.set(key, text);
+            const inflight = this.inflight.get(key);
+            if (inflight) {
+                waiting.set(key, inflight);
+            }
+            else {
+                const deferred = createDeferred();
+                this.inflight.set(key, deferred.promise);
+                owned.set(key, { text, deferred });
+            }
+        }
+        const resolved = new Map();
+        // Resolve owned keys from the cache; the rest need the adapter
+        const misses = [];
+        await Promise.all(Array.from(owned, async ([key, { text, deferred }]) => {
+            const cached = this.cache ? await this.cache.get(key) : undefined;
+            if (cached !== undefined) {
+                resolved.set(key, cached);
+                deferred.resolve(cached);
+                this.inflight.delete(key);
+            }
+            else {
+                misses.push({ key, text, deferred });
+            }
+        }));
+        if (misses.length > 0) {
+            try {
+                const out = await this.adapter.translate({
+                    texts: misses.map((miss) => miss.text),
+                    from,
+                    to,
+                });
+                if (out.length !== misses.length) {
+                    throw new Error(`AIAdapter returned ${out.length} texts, expected ${misses.length}`);
+                }
+                await Promise.all(misses.map(async (miss, i) => {
+                    const translated = out[i];
+                    resolved.set(miss.key, translated);
+                    miss.deferred.resolve(translated);
+                    await this.cache?.set(miss.key, translated);
+                }));
+            }
+            catch (err) {
+                for (const miss of misses)
+                    miss.deferred.reject(err);
+                if (this.onError === "throw")
+                    throw err;
+                for (const miss of misses)
+                    resolved.set(miss.key, miss.text);
+            }
+            finally {
+                for (const miss of misses)
+                    this.inflight.delete(miss.key);
+            }
+        }
+        // Wait for keys owned by other concurrent calls
+        await Promise.all(Array.from(waiting, async ([key, promise]) => {
+            try {
+                resolved.set(key, await promise);
+            }
+            catch (err) {
+                if (this.onError === "throw")
+                    throw err;
+                resolved.set(key, textByKey.get(key));
+            }
+        }));
+        return keys.map((key) => resolved.get(key));
+    }
+    /**
+     * Fill in missing locales of static message entries.
+     * Existing translations are kept; only missing ones are translated
+     * from the source locale. The result can be passed to ChainBuilder.add().
+     */
+    async completeEntries(locales, entries) {
+        const source = this.sourceLocale;
+        if (source === undefined) {
+            throw new Error("completeEntries requires the sourceLocale option");
+        }
+        const result = {};
+        for (const [key, entry] of Object.entries(entries)) {
+            if (typeof entry[source] !== "string") {
+                throw new Error(`Entry "${key}" is missing source locale "${source}"`);
+            }
+            result[key] = { ...entry };
+        }
+        await Promise.all(locales
+            .filter((locale) => locale !== source)
+            .map(async (locale) => {
+            const missing = Object.values(result).filter((entry) => entry[locale] === undefined);
+            if (missing.length === 0)
+                return;
+            const translated = await this.translateMany(missing.map((entry) => entry[source]), { to: locale, from: source });
+            for (const [i, entry] of missing.entries()) {
+                entry[locale] = translated[i];
+            }
+        }));
+        return result;
+    }
+}
+export function createAITranslator(options) {
+    return new AITranslator(options);
+}

package/dist/adaptors/ai/translator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adaptors/ai/translator.test.js

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+import { memoryCache } from "./cache.js";
+import { createAITranslator } from "./translator.js";
+function fakeAdapter() {
+    const calls = [];
+    const adapter = {
+        async translate(request) {
+            calls.push(request);
+            return request.texts.map((text) => `${text}[${request.to}]`);
+        },
+    };
+    return { adapter, calls };
+}
+describe("AITranslator", () => {
+    it("translates a single text via the adapter", async () => {
+        const { adapter, calls } = fakeAdapter();
+        const translator = createAITranslator({ adapter, sourceLocale: "ja" });
+        const result = await translator.translate("こんにちは", { to: "en" });
+        expect(result).toBe("こんにちは[en]");
+        expect(calls).toEqual([{ texts: ["こんにちは"], from: "ja", to: "en" }]);
+    });
+    it("passes from: undefined to the adapter when the source language is unknown", async () => {
+        const { adapter, calls } = fakeAdapter();
+        const translator = createAITranslator({ adapter });
+        const result = await translator.translate("こんにちは", { to: "en" });
+        expect(result).toBe("こんにちは[en]");
+        expect(calls).toEqual([{ texts: ["こんにちは"], from: undefined, to: "en" }]);
+    });
+    it("calls the adapter even when to may equal the unknown source language", async () => {
+        const { adapter, calls } = fakeAdapter();
+        const translator = createAITranslator({ adapter });
+        await translator.translate("こんにちは", { to: "ja" });
+        expect(calls).toHaveLength(1);
+    });
+    it("rejects completeEntries without sourceLocale", async () => {
+        const { adapter } = fakeAdapter();
+        const translator = createAITranslator({ adapter });
+        await expect(translator.completeEntries(["ja", "en"], {
+            title: { ja: "タイトル" },
+        })).rejects.toThrow("requires the sourceLocale option");
+    });
+    it("returns texts as-is when from equals to", async () => {
+        const { adapter, calls } = fakeAdapter();
+        const translator = createAITranslator({ adapter, sourceLocale: "ja" });
+        const result = await translator.translate("こんにちは", { to: "ja" });
+        expect(result).toBe("こんにちは");
+        expect(calls).toHaveLength(0);
+    });
+    it("batches multiple texts into one adapter call", async () => {
+        const { adapter, calls } = fakeAdapter();
+        const translator = createAITranslator({ adapter, sourceLocale: "ja" });
+        const result = await translator.translateMany(["a", "b"], { to: "en" });
+        expect(result).toEqual(["a[en]", "b[en]"]);
+        expect(calls).toHaveLength(1);
+    });
+    it("deduplicates the same text within a batch", async () => {
+        const { adapter, calls } = fakeAdapter();
+        const translator = createAITranslator({ adapter, sourceLocale: "ja" });
+        const result = await translator.translateMany(["a", "a", "b"], { to: "en" });
+        expect(result).toEqual(["a[en]", "a[en]", "b[en]"]);
+        expect(calls[0]?.texts).toEqual(["a", "b"]);
+    });
+    it("uses the cache to avoid repeated adapter calls", async () => {
+        const { adapter, calls } = fakeAdapter();
+        const translator = createAITranslator({
+            adapter,
+            sourceLocale: "ja",
+            cache: memoryCache(),
+        });
+        await translator.translate("a", { to: "en" });
+        const result = await translator.translate("a", { to: "en" });
+        expect(result).toBe("a[en]");
+        expect(calls).toHaveLength(1);
+    });
+    it("deduplicates concurrent requests for the same text", async () => {
+        const calls = [];
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const adapter = {
+            async translate(request) {
+                calls.push(request);
+                await gate;
+                return request.texts.map((text) => `${text}[${request.to}]`);
+            },
+        };
+        const translator = createAITranslator({ adapter, sourceLocale: "ja" });
+        const first = translator.translate("a", { to: "en" });
+        const second = translator.translate("a", { to: "en" });
+        await Promise.resolve();
+        release();
+        expect(await first).toBe("a[en]");
+        expect(await second).toBe("a[en]");
+        expect(calls).toHaveLength(1);
+    });
+    it("falls back to the original text on adapter error by default", async () => {
+        const adapter = {
+            async translate() {
+                throw new Error("api down");
+            },
+        };
+        const translator = createAITranslator({ adapter, sourceLocale: "ja" });
+        const result = await translator.translate("こんにちは", { to: "en" });
+        expect(result).toBe("こんにちは");
+    });
+    it("throws on adapter error when onError is 'throw'", async () => {
+        const adapter = {
+            async translate() {
+                throw new Error("api down");
+            },
+        };
+        const translator = createAITranslator({
+            adapter,
+            sourceLocale: "ja",
+            onError: "throw",
+        });
+        await expect(translator.translate("こんにちは", { to: "en" })).rejects.toThrow("api down");
+    });
+    it("throws when the adapter returns a wrong number of texts", async () => {
+        const adapter = {
+            async translate() {
+                return [];
+            },
+        };
+        const translator = createAITranslator({
+            adapter,
+            sourceLocale: "ja",
+            onError: "throw",
+        });
+        await expect(translator.translate("a", { to: "en" })).rejects.toThrow("expected 1");
+    });
+    it("completes missing locales of entries, keeping existing translations", async () => {
+        const { adapter, calls } = fakeAdapter();
+        const translator = createAITranslator({ adapter, sourceLocale: "ja" });
+        const entries = await translator.completeEntries(["ja", "en", "fr"], {
+            title: { ja: "タイトル" },
+            greeting: { ja: "こんにちは", en: "Hello" },
+        });
+        expect(entries).toEqual({
+            title: { ja: "タイトル", en: "タイトル[en]", fr: "タイトル[fr]" },
+            greeting: { ja: "こんにちは", en: "Hello", fr: "こんにちは[fr]" },
+        });
+        // en: title のみ / fr: title と greeting
+        expect(calls).toHaveLength(2);
+    });
+    it("throws when an entry is missing the source locale", async () => {
+        const { adapter } = fakeAdapter();
+        const translator = createAITranslator({ adapter, sourceLocale: "ja" });
+        await expect(translator.completeEntries(["ja", "en"], {
+            title: { en: "Title" },
+        })).rejects.toThrow('missing source locale "ja"');
+    });
+});

package/dist/adaptors/ai/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal interface for an AI translation backend.
+ * Implement this to plug in any provider (OpenAI, local model, etc.).
+ */
+export interface AIAdapter {
+    /**
+     * Translate texts from one locale to another.
+     * Must return translations in the same order and length as `texts`.
+     */
+    translate(request: AITranslateRequest): Promise<string[]>;
+}
+export interface AITranslateRequest {
+    texts: string[];
+    /** Omitted when the source language is unknown — detect it from the texts. */
+    from?: string;
+    to: string;
+}
+/**
+ * Cache for translated texts.
+ * Implement this to persist translations anywhere (memory, DB, file, etc.).
+ */
+export interface TranslationCache {
+    get(key: string): Promise<string | undefined> | string | undefined;
+    set(key: string, value: string): Promise<void> | void;
+}

package/dist/adaptors/ai/types.js

@@ -0,0 +1 @@
+export {};

package/dist/adaptors/next/_client.d.ts

@@ -21,7 +21,7 @@ export interface ClientLocaleProviderProps {
     useLocaleSource?: UseLocaleSource;
     pathPrefix?: string;
 }
-export declare function ClientLocaleProvider({ children, locales, fallbackLocale, paramKey, useLocaleSource, pathPrefix, }: ClientLocaleProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientLocaleProvider({ children, locales, fallbackLocale, paramKey, useLocaleSource, pathPrefix, }: ClientLocaleProviderProps): import("react").JSX.Element;
 export declare function useLocaleClient(): LocaleContextValue;
 export declare function useBindLocaleClient<T extends object>(messages: T): unknown;
 export interface ClientLocaleLinkProps extends Omit<ComponentProps<typeof Link>, "href" | "locale"> {
@@ -29,4 +29,4 @@ export interface ClientLocaleLinkProps extends Omit<ComponentProps<typeof Link>,
     href?: string;
     children?: ReactNode;
 }
-export declare function ClientLocaleLink({ locale, href, children, ...rest }: ClientLocaleLinkProps): import("react/jsx-runtime").JSX.Element;
+export declare function ClientLocaleLink({ locale, href, children, ...rest }: ClientLocaleLinkProps): import("react").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-i18n",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "The Type-Safe i18n library that your IDE will Love",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,11 @@
       "types": "./dist/adaptors/next/index.d.ts",
       "import": "./dist/adaptors/next/index.js",
       "default": "./dist/adaptors/next/index.js"
+    },
+    "./ai": {
+      "types": "./dist/adaptors/ai/index.d.ts",
+      "import": "./dist/adaptors/ai/index.js",
+      "default": "./dist/adaptors/ai/index.js"
     }
   },
   "peerDependencies": {
@@ -54,12 +59,12 @@
   "devDependencies": {
     "@tsconfig/node20": "^20.1.9",
     "@types/node": "^25.9.1",
-    "@types/react": "^19.2.15",
+    "@types/react": "^19.2.16",
     "next": "16",
-    "react": "^19.2.6",
-    "release-it": "^19.2.4",
+    "react": "^19.2.7",
+    "release-it": "^20.2.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "keywords": [
     "i18n",

package/skills/SKILL.md

@@ -225,6 +225,41 @@ React is a `peerDependency` (`>=18`).
 
 ---
 
+## AI Translation
+
+`canopy-i18n/ai` provides a runtime translator with a pluggable adapter (bring any AI backend). Static strings only — template functions are not translated. See README for details.
+
+```ts
+import { createAITranslator, memoryCache, openAIAdapter } from 'canopy-i18n/ai';
+
+const translator = createAITranslator({
+  // Built-in adapters: openAIAdapter / anthropicAdapter / geminiAdapter
+  // (fetch-based; model & apiKey required; baseURL/instructions optional).
+  // Or implement AIAdapter yourself: { async translate({ texts, from, to }) {...} }
+  // (`from` is undefined when the source language is unknown — auto-detect it)
+  adapter: openAIAdapter({ model: 'gpt-4o-mini', apiKey: process.env.OPENAI_API_KEY! }),
+  sourceLocale: 'ja',       // default `from` (optional; required for completeEntries)
+  cache: memoryCache(),     // optional; custom { get, set } for DB persistence
+  // onError: 'fallback'    // default: return original text on failure ('throw' to propagate)
+});
+
+// Custom adapters can reuse the built-in prompt logic:
+// buildTranslatePrompt(request, { instructions }) / parseTranslatedTexts(raw, expected)
+
+// Dynamic texts (e.g. user input) — cached, deduplicated, batched
+await translator.translate(userInput, { to: 'en' });          // from = sourceLocale
+await translator.translate(userInput, { to: 'en', from: 'fr' });
+// Without sourceLocale and `from`, the adapter auto-detects the source language
+
+// Fill missing locales of entries, then pass to ChainBuilder.add()
+const entries = await translator.completeEntries(['ja', 'en'] as const, {
+  title: { ja: 'タイトル' },  // en is AI-translated; existing values are kept
+});
+const messages = createI18n(['ja', 'en'] as const).add(entries).build('en');
+```
+
+---
+
 ## Exports
 
 ```ts
@@ -242,4 +277,10 @@ export {
   createStorageI18nReact,
   createCookieI18nReact,
 } from 'canopy-i18n/react';
+
+// AI subpath
+export { createAITranslator, AITranslator, memoryCache } from 'canopy-i18n/ai';
+export { openAIAdapter, anthropicAdapter, geminiAdapter } from 'canopy-i18n/ai';
+export { buildTranslatePrompt, parseTranslatedTexts } from 'canopy-i18n/ai';
+export type { AIAdapter, TranslationCache } from 'canopy-i18n/ai';
 ```