Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 114 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ npx rosetta check # CI gate: fails if anything is stale or broken (no API ke
- [Coming from Lingo.dev](#coming-from-lingodev)
- [Library API](#library-api)
- [React & Next.js](#react--nextjs)
- [Locale routing & cookies](#locale-routing--cookies)
- [Development](#development)

## Quick start
Expand Down Expand Up @@ -555,6 +556,119 @@ the route handler or Server Action above.
> Node-only workflow (`push`, `check`, …, which read and write files), so prefer the
> `next` entrypoint in edge code.

## Locale routing & cookies

Translating strings is half the job. Knowing *which* locale a request is in — and
switching cleanly — is the other half, and it's where most apps hand-roll fragile
middleware, server actions, and `router.refresh()` races. Rosetta ships the runtime
layer too: `rosetta-i18n/locale` (core), `/react`, `/next`, `/astro`.

The model is one-directional and needs no client-side guessing:

1. a **locale-prefixed URL** (`/ja/pricing`) is authoritative,
2. then a **forced header** (`x-rosetta-locale`, set by middleware),
3. then the **cookie**,
4. then the **default locale**.

**Switching writes the cookie and navigates to the localized URL**, so the URL and the
cookie always agree. A full-page navigation makes it a single request with no
refresh-after-push race.

### Config (plain data)

```ts
// i18n/config.ts
import type { LocaleConfig } from "rosetta-i18n/locale";

export const localeConfig: LocaleConfig = {
locales: ["en", "ja", "de", "es"],
defaultLocale: "en",
// Only these paths have localized variants; everything else stays bare.
localizedPaths: ["/", "/pricing", "/agents"],
localizedPathPrefixes: ["/blog/", "/help/", "/vs/"],
};
```

The core also exports the pure helpers (`resolveLocale`, `stripLocale`, `localizePath`,
`planSwitch`, `serializeLocaleCookie`, …) if you're wiring your own framework.

### React

```tsx
"use client";
import { LocaleProvider, LocaleSwitcher } from "rosetta-i18n/react";

export function App({ locale, children }: { locale: string; children: React.ReactNode }) {
return (
<LocaleProvider config={localeConfig} locale={locale}>
{/* or render={({ locales, locale, switchTo, labelFor }) => …} */}
<LocaleSwitcher />
{children}
</LocaleProvider>
);
}
```

Hooks: `useLocale()`, `useLocales()`, `useLocaleSwitch()`, `useLocaleContext()`.
`switchTo(locale)` writes the cookie and navigates (full page by default; pass
`navigate` to hook a router, `persist` to save server-side).

### Next.js (App Router)

```ts
// middleware.ts
import { createLocaleMiddleware } from "rosetta-i18n/next";
import { localeConfig } from "./i18n/config";

export const middleware = createLocaleMiddleware(localeConfig);
export const config = { matcher: ["/((?!_next|favicon.ico|.*\\..*).*)"] };
```

```tsx
// app/layout.tsx
import { RosettaProvider } from "rosetta-i18n/next";
import { localeConfig } from "@/i18n/config";

export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<RosettaProvider config={localeConfig}>{children}</RosettaProvider>
</body>
</html>
);
}
```

`RosettaProvider` reads the locale the middleware forced (`getServerLocale(config)`)
and provides it to the client. Persist the choice for signed-in users with a server
action:

```ts
// app/locale-actions.ts
"use server";
import { createSetLocaleAction } from "rosetta-i18n/next";
import { localeConfig } from "@/i18n/config";

export const setLocale = createSetLocaleAction(localeConfig, {
persist: (locale) => updateUserProfile(userId, { locale }),
});
```

### Astro

```ts
// src/middleware.ts
import { createAstroLocaleMiddleware } from "rosetta-i18n/astro";
import { localeConfig } from "../i18n/config";

export const onRequest = createAstroLocaleMiddleware(localeConfig);
```

The middleware sets `Astro.locals.locale` (read it with `getAstroLocale(Astro, config)`)
and rewrites prefixed URLs. For a switcher, render the React `<LocaleSwitcher>` as an
island wrapped in `<LocaleProvider locale={Astro.locals.locale} config={localeConfig}>`.

## Legacy `translate-catalog`

The 0.x one-shot command still works but is deprecated and will be removed in v2:
Expand Down
24 changes: 23 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,18 @@
"types": "./dist/types/next.d.ts",
"default": "./dist/esm/next.js"
},
"./react": {
"types": "./dist/types/react.d.ts",
"default": "./dist/esm/react.js"
},
"./astro": {
"types": "./dist/types/locale/astro.d.ts",
"default": "./dist/esm/astro.js"
},
"./locale": {
"types": "./dist/types/locale/core.d.ts",
"default": "./dist/esm/locale.js"
},
"./config": {
"types": "./dist/types/config.d.ts",
"default": "./dist/esm/config.js"
Expand All @@ -67,16 +79,26 @@
"lint:fix": "biome check --write"
},
"peerDependencies": {
"next": ">=14.0.0"
"astro": ">=4.0.0",
"next": ">=14.0.0",
"react": ">=18.0.0"
},
"peerDependenciesMeta": {
"next": {
"optional": true
},
"react": {
"optional": true
},
"astro": {
"optional": true
}
},
"devDependencies": {
"@biomejs/biome": "2.5.12",
"@types/node": "22.15.3",
"@types/react": "^19.3.0",
"react": "^19.3.0",
"rollup": "^4.63.1",
"rollup-plugin-esbuild": "^6.1.1",
"typescript": "5.9.2",
Expand Down
Loading
Loading