Configure server rendering
Import server helpers from @linguanahq/react/ssr. Resolve once per request, load only a verified catalog, and pass the resulting hydration state unchanged to the browser.
This guide applies to React servers you wire yourself, such as TanStack Start. In Next.js, LinguanaProvider from @linguanahq/next/server performs these steps for every request; see the Next.js guide.
Locale precedence
| Priority | Source | Typical owner |
|---|---|---|
| 1 | Explicit override | Application route policy |
| 2 | userPreference | Signed-in account |
| 3 | linguana_locale cookie | Prior language selection |
| 4 | Weighted Accept-Language | Browser |
| 5 | defaultLocale | Project/application |
Exact locale matches win before language-only matches, so fr-CA may match configured fr.
import { resolveRequestLocale } from "@linguanahq/react/ssr";
const locale = resolveRequestLocale({
request,
override: routeLocale,
userPreference: account?.locale,
supportedLocales: ["en", "fr", "am"],
defaultLocale: "en",
});Load and serialize
Attempt target catalog loading on the server. If it fails, keep the requested enabled locale for formatting and direction, with the embedded source catalog for text fallback.
const requested = resolveRequestLocale({
request,
supportedLocales: ["en", "fr"],
defaultLocale: "en",
});
const target = requested === "en"
? undefined
: await loadCatalog({
endpoint: process.env.LINGUANA_API_URL!,
projectId,
environment,
locale: requested,
publishableKey: process.env.LINGUANA_PUBLISHABLE_KEY!,
}).catch(() => undefined);
const hydrationState = createRequestHydrationState(
requested,
target ? [embeddedEnglish, target] : [embeddedEnglish],
"UTC",
);Pass hydrationState to LocaleProvider. It contains schema version 1, the resolved locale, and validated catalogs.
Cookie and route ownership
The default cookie is first-party, path-wide, and SameSite=Lax. Linguana does not redirect or add locale path segments. If the application owns localized routes, pass that locale as override and keep URL generation in the router.
Public pages and search discovery
Translating the interface does not create separately indexable language pages. A language preference stored in a cookie is different from a stable URL for each translation.
For public React or TanStack Start pages that need language-specific search discovery, your application owns the locale URLs, links, page titles, descriptions, canonical URLs, and reciprocal hreflang annotations. Resolve each route's locale on the server and pass it as override so the delivered HTML and browser hydration agree. Keep each language reachable through ordinary links without requiring a saved cookie or language-picker interaction.
Google recommends separate URLs for different language versions and warns that automatic language redirects can prevent discovery. Follow its multilingual site guidance when designing those routes.
The current Next.js integration does not include localized URL routing. Evaluate that limitation before choosing it for a multilingual marketing site.
Next
Use the SSR API reference and add the precedence cases to integration testing.
Resolve request locale and hydrate React with the same verified catalog state.
Last updated November 17, 2026
Did this page get you to a working result?