Waku i18n · React Server Components
Waku i18n across React Server and Client Components.
Palamedes keeps translation state aligned across Waku's React Server Component tree and its hydrated client islands. A Vite adapter transforms messages; the shared runtime resolves the active catalog on the correct side of the boundary.
Palamedes 2.0 is out. Read the release notes.
- Build integration
- @palamedes/vite-plugin
- Verified against
- Waku 1 RC
- Rendering
- RSC + islands
- Locale models
- 4 examples
Configured inside Waku's Vite plugin surface.
React 19.3.1 Server Components on 1.0.0-rc.4.
Server-first pages with hydrated client boundaries.
Cookie, route, subdomain, and top-level domain.
@palamedes/wakuv2.2.0975 downloads / month01 — The framework problem
RSC moves the translation boundary before the traditional client application starts.
Waku begins with a Server Component tree, then introduces client boundaries only where interactivity is needed. Locale state must be available in both environments without shipping server machinery to the browser or rendering two languages during hydration.
02 — The Palamedes model
Treat the server and client as two hosts of one compiled message model.
Palamedes keeps the environment-specific activation explicit while sharing authoring, catalogs, ICU semantics, and diagnostics across the RSC boundary.
Waku-native Vite composition
Add the Palamedes transform through Waku's vite.plugins configuration beside the React plugin already used by the application.
Server-first activation
Resolve the request locale and activate a fresh i18n instance before the Server Component page calls t or Trans.
Small client boundaries
Only interactive islands load the React client helpers. Server-rendered translated content does not require turning the whole page into a Client Component.
03 — In TypeScript
Palamedes joins Waku's Vite pipeline without changing the RSC page model.
waku.config.ts + pages/[locale].tsx
// waku.config.ts
import react from "@vitejs/plugin-react"
import { defineConfig } from "waku/config"
import { palamedes } from "@palamedes/vite-plugin"
export default defineConfig({
vite: {
plugins: [
palamedes(),
react(),
],
},
})
// pages/[locale].tsx — a Server Component
import { Trans } from "@palamedes/react/macro"
export default async function LocalePage() {
return <h1><Trans>Welcome to Palamedes</Trans></h1>
}The checked example resolves the request locale before this page renders. The adapter initializes interactive client modules and loads their active-locale fragments; the application supplies ordinary error UI. Locale changes navigate to a new document.
04 — Locale strategy
Choose the URL model that fits your Waku product.
Waku decides how pages map to URLs and requests. Palamedes keeps the RSC and client translation model fixed while the matrix changes where the locale is detected and how a switch is represented.
Cookie
One URL for all locales. Useful for signed-in apps; an explicit language choice is persisted and opens a new document in that locale.
Route segment
/de/checkout-style paths. The SEO-friendly default for public content with indexable localized pages.
Subdomain
de.example.com. Clean separation per market, works well with regional CDNs and analytics splits.
05 — Proof and boundaries
The matrix exercises both halves of the React Server Component architecture.
Waku has its own browser-verified example family. It is not counted as proof merely because the Next.js adapter also supports Server Components.
- Server tree
- RSC checked
- Client boundary
- Island checked
- Locale behavior
- 4 strategies
- Evidence
- Live + source
Translated output is rendered in the server-first page.
Interactive translated components hydrate and switch.
Host and path decisions are verified separately.
All four strategies are live and linked alongside their checked source.
06 — Questions
Waku i18n questions, answered
The short version of the decisions that usually block an implementation.
- Can Palamedes translate Waku Server Components?
- Yes. Activate the request's i18n instance before the Server Component tree executes translated macros. The checked Waku examples render localized server output for all four locale strategies.
- Do translated Waku pages become Client Components?
- No. Server Components render translated messages on the server. Interactive islands use the adapter's browser delivery. A locale change navigates to a new document so server output and browser messages remain aligned.
- How does the locale cross the RSC boundary?
- The server resolves the locale and loads shared immutable catalog messages with isolated request state. The adapter loads that document locale's compiled fragments before interactive translated modules run.
- Is Waku support production-stable?
- The adapter is Stable for waku@^1.0.0-rc.4, verified with Waku 1.0.0-rc.4, which is an upstream release candidate. It uses Waku's unstable request and nonce APIs, so the peer range moves only after a new Waku version passes the regression proofs.
07 — Keep exploring