Skip to Content

Framework request adapters

Resolve request locales from Next.js App Router, TanStack Router, and React Router loaders.

The framework subpaths adapt native request values to the same locale resolution order: route locale, locale cookie, Accept-Language, then the configured default. They do not register routes, rewrite URLs, or create framework-global locale state. Pass the resolved locale into the React provider or create a request-scoped translator on the server.

Next.js App Router

Next.js 15/16 request APIs are asynchronous. Resolve the route params and headers in the server layout or page:

import { headers } from "next/headers";
import { resolveNextRequestLocale } from "@puzzle-ui/i18n/next";
import { createI18nReact } from "@puzzle-ui/i18n/react";
import type { ReactNode } from "react";
import { i18n } from "./i18n";

const { Provider: I18nProvider } = createI18nReact(i18n);

export default async function LocaleLayout({
  children,
  params,
}: {
  children: ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const [routeParams, requestHeaders] = await Promise.all([
    params,
    headers(),
  ]);
  const { locale } = resolveNextRequestLocale({
    registry: i18n.registry,
    headers: requestHeaders,
    urlLocale: routeParams.locale,
  });

  return <I18nProvider locale={locale}>{children}</I18nProvider>;
}

Call the adapter in a request-bound server component; do not cache its result across requests. Next.js 16 awaits route params and headers, so do not pass synchronous values.

TanStack Router / Start

The adapter returns a native route-loader-compatible function using the Request and route params supplied by TanStack:

import { createFileRoute } from "@tanstack/react-router";
import { createTanStackLocaleLoader } from "@puzzle-ui/i18n/tanstack";
import { i18n } from "./i18n";

const resolveLocale = createTanStackLocaleLoader({
  registry: i18n.registry,
});

export const Route = createFileRoute("/$locale")({
  loader: (args) => resolveLocale(args),
});

Use the loader result in the route component and provide it to the React bindings. For Start, run request-dependent catalog loading only on the server; the browser imports must not include @puzzle-ui/i18n/sources/node.

React Router

The React Router 7 adapter accepts the native LoaderFunctionArgs request and params:

import type { Route } from "./+types/locale";
import { createReactRouterLocaleLoader } from "@puzzle-ui/i18n/react-router";
import { i18n } from "./i18n";

const resolveLocale = createReactRouterLocaleLoader({
  registry: i18n.registry,
});

export function loader(args: Route.LoaderArgs) {
  return resolveLocale(args);
}

Use React Router's metadata APIs and navigation primitives directly. The adapter does not implement route registration, localized slugs, or redirects; use @puzzle-ui/i18n/routing for same-origin path generation.

Verified native fixtures

The repository includes fixture applications that exercise framework-owned request, route, rendering, and navigation APIs rather than mocking them.

Next.js App Router

apps/workspace-next covers statically generated /localized/en and /localized/fr pages, /localized/fr/stream, and a dynamic /locale-request page. Its Next.js 16 src/proxy.ts matches /localized/:path* but redirects only the bare /localized path. Locale preference is cookie, then Accept-Language, then the default en; redirects preserve query parameters, and an unsupported URL locale returns 404.

The fixture exercises async route params, generateStaticParams with dynamicParams = false, localized generateMetadata including Open Graph locale, asynchronous headers()/cookies(), React cache() for request-scoped deduplication, and <Suspense> around an async Server Component for streaming. A route locale takes precedence over request preferences.

TanStack Start and Router

apps/workspace-tanstack exercises the /multilingual route with ?locale=fr&q=projet. validateSearch restricts locales and bounds the query; beforeLoad provides locale context; loaderDeps and loader load data for the selected locale through a GET createServerFn. Locale links preserve the search query, and useNavigate updates the query and filters localized topics. The rendered route exposes the locale's lang and dir.

The fixture uses createFileRoute, Route.useLoaderData, Route.useSearch, Route.useRouteContext, Link, and useNavigate, and is typechecked, render-tested, and production-built.

React Router

apps/workspace-react-router is a React Router 7 data-router application with SSR and client hydration. It serves /en/workspace, /fr/workspace, and /ar/workspace; / redirects to /en/workspace, and /xx/workspace exercises the unsupported-locale error boundary. The localized page uses ?q=membres search state, native loader/action data, and route handle metadata. Its production browser test verifies no-JavaScript SSR, hydration, locale navigation, metadata updates, search navigation, form actions, and errors.

The app uses React Router's createStaticHandler, createStaticRouter, and StaticRouterProvider for server rendering and createBrowserRouter and RouterProvider for client hydration, with useMatches for metadata. The package suite also retains a small static data-router contract test. React Router remains an optional peer; no framework dependency is loaded by the package root.

Run bun run test:frameworks for the Next.js and TanStack app typecheck, rendering, and production-build matrix, including React Router's typecheck, production client/SSR build, and rendering/browser suite. Run bun run --filter @puzzle-ui/i18n test:unit for the package's static React Router contract test; public entrypoints are covered by test:package.