rosetta-i18n 0.1.1 → 0.1.2

package/README.md

@@ -101,6 +101,146 @@ const out = await rosetta.translate(
 Translates a single string. Throws on a non-OK response (unlike `translate`,
 which degrades gracefully at the batch level).
 
+## React & Next.js
+
+Rosetta calls an LLM with your API key, so it runs **server-side only**. Never
+import it in a Client Component (`"use client"`) — bundle the key out with
+[`server-only`](https://www.npmjs.com/package/server-only) and expose
+translations through server code.
+
+```bash
+pnpm add rosetta-i18n server-only
+```
+
+### One shared instance
+
+```ts
+// lib/rosetta.ts
+import "server-only";
+import { Rosetta } from "rosetta-i18n";
+
+export 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" } },
+});
+```
+
+### Recommended: pre-translate message catalogs at build time
+
+For `next-intl` / `react-i18next`, translate the locale JSON once and ship it —
+no LLM call in the request path.
+
+```ts
+// scripts/translate-catalog.ts — run with `tsx`
+import { writeFile } from "node:fs/promises";
+import { Rosetta } from "rosetta-i18n";
+import en from "../messages/en.json";
+
+const rosetta = new Rosetta({
+	apiKey: process.env.OPENROUTER_API_KEY!,
+	model: "anthropic/claude-sonnet-4.5",
+	brandVoice: { variations: { "*": "Editorial, concise." } },
+});
+
+for (const target of ["es", "pt-BR"]) {
+	const messages = await rosetta.translate(en, {
+		source: "en",
+		target,
+		context: "Next.js UI catalog",
+		hints: { "nav.bookings": ["navigation", "top bar"] },
+	});
+	await writeFile(
+		`messages/${target}.json`,
+		JSON.stringify(messages, null, 2),
+	);
+}
+```
+
+```ts
+// i18n/request.ts (next-intl)
+import { getRequestConfig } from "next-intl/server";
+
+export default getRequestConfig(async ({ locale }) => ({
+	messages: (await import(`../messages/${locale}.json`)).default,
+}));
+```
+
+### Server Component (RSC)
+
+```tsx
+// app/[locale]/hero.tsx
+import { rosetta } from "@/lib/rosetta";
+
+export async function Hero({ locale }: { locale: string }) {
+	const copy = await rosetta.translate(
+		{ hero: "Every awarded restaurant in the world" },
+		{ source: "en", target: locale, context: "home hero" },
+	);
+	return <h1>{String(copy.hero)}</h1>;
+}
+```
+
+Cache per-request translations with React's `cache` or
+`unstable_cache` so they aren't re-fetched on every render:
+
+```ts
+import { unstable_cache } from "next/cache";
+import { rosetta } from "@/lib/rosetta";
+
+export const translateCached = unstable_cache(
+	async (data: Record<string, string>, target: string) =>
+		rosetta.translate(data, { source: "en", target }),
+	["rosetta"],
+	{ revalidate: 60 * 60 * 24 },
+);
+```
+
+### Route Handler
+
+```ts
+// app/api/translate/route.ts
+import { NextResponse } from "next/server";
+import { rosetta } from "@/lib/rosetta";
+
+export async function POST(req: Request) {
+	const { data, target, context } = await req.json();
+	const translated = await rosetta.translate(data, {
+		source: "en",
+		target,
+		context,
+	});
+	return NextResponse.json(translated);
+}
+```
+
+### Server Action
+
+```ts
+// app/actions.ts
+"use server";
+import { rosetta } from "@/lib/rosetta";
+
+export async function translateBlurb(blurb: string, target: string) {
+	return rosetta.translateText(blurb, { source: "en", target });
+}
+```
+
+### Client Components
+
+Client Components consume already-translated strings via props, context, or the
+catalog — they never import Rosetta. To trigger a translation from the browser,
+call the route handler or Server Action above.
+
+> **Edge runtime:** Rosetta only uses `fetch`, so it works on the Edge runtime as
+> long as your endpoint does. Node runtime is recommended for large catalogs.
+
 ## Releasing
 
 Releases publish automatically from GitHub Actions via npm

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rosetta-i18n",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"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.",