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.

Locale precedence

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, return source locale and the embedded catalog instead of claiming the unavailable target.

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(
  target ? requested : "en",
  target ? [embeddedEnglish, target] : [embeddedEnglish],
);

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.

Next

Use the SSR API reference and add the precedence cases to integration testing.