SSR-Safe Internationalization in TanStack Start with i18next

SSR can be tricky, mostly because every framework does things its own way. Loaders, lifecycles, hydration, serialization all behave a little differently depending on where you are, so wiring up something like i18next is rarely a copy-paste between frameworks. i18next has solid SSR support, but how you connect it still depends on the framework you're using.

This post focuses on TanStack Start specifically:

Detecting the user's preferred language on the server.
Initializing separate i18next instances for server and client.
Safely passing an i18next instance across the server-to-client boundary without things quietly breaking.

By the end you'll have a working pattern that you can adapt to your own projects.

If you'd rather learn by reading the finished code, the full project is on GitHub: https://github.com/ookamiiixd/tanstack-start-i18next

A quick heads-up before we start: everything here is based on my own testing and experience, not official guidance, so I might have gotten some details wrong. If you spot a mistake or know a better way to do something, I'd genuinely welcome the correction or suggestion.

Understanding the Strategy
Prerequisites
Project Structure
Setting Up i18next
Wiring Up TanStack Start
Using Translations
Gotchas
Wrap-up

Understanding the Strategy

This guide follows the strategy below. Feel free to adjust it to your needs.

Language detection (in order of priority): optional path param, then cookie, then the Accept-Language header.
Translation resources live in public/translations and are served as static JSON files.
On the server, resources for all languages are bundled together. This keeps things simple, and bundling everything upfront is cheap on the server.
On the client, resources load selectively by namespace using TanStack Router's staticData, and anything else is fetched lazily through i18next-http-backend. Depending on the size of your translations, you might prefer bundling all resources for one language, or all resources for every language.

Prerequisites

Make sure you have a TanStack Start project ready. Use your own, pick one from the examples, or scaffold a new one:

npx @tanstack/cli@latest create

Install the dependencies:

npm i i18next i18next-http-backend react-i18next

For convenience this guide also uses accept-language-parser to parse the Accept-Language header:

npm i accept-language-parser
npm i -D @types/accept-language-parser

Project Structure

src
│   client.tsx        // Client entrypoint, recovers the i18n instance and hydrates
│   router.tsx        // Router factory + type augmentations
│   server.tsx        // Server entrypoint, builds the per-request i18n instance and request context
│   start.ts          // Start config, registers the i18n serialization adapter
│
├───lib
│   └───i18n
│           client.ts      // Client instance (HTTP backend, lazy namespaces) + cookie helpers
│           config.ts      // Shared i18next config + cookie key
│           index.ts       // Isomorphic facade: instance/language helpers, getFixedT, serialization adapter
│           resources.ts   // Bundled resources + type-safe keys
│           server.ts      // Server instance (all resources bundled) + language detection
│
└───routes
    │   __root.tsx    // Language resolution & redirect, document shell, SSR resource serialization
    │
    └───{-$lang}
            route.tsx     // Language layout (validates the lang param, nav + switcher)
            index.tsx     // Home page

public
└───translations    // Translation files
    ├───en
    │       common.json
    │       ...
    │
    └───id
            common.json
            ...

The {-$lang} segment is an optional path param. It matches / (no prefix, used for the fallback language) as well as /en and /id.

Setting Up i18next

1. Translation files

Create translation files for at least two languages:

// public/translations/en/common.json
{ /* ... */ }

// public/translations/id/common.json
{ /* ... */ }

2. Shared config

This config is shared by both instances. Adjust it to your needs. The ns list is the set of namespaces that are always loaded; per-route namespaces come later through staticData, so keep this list small.

// src/lib/i18n/config.ts
import type { FlatNamespace, InitOptions } from "i18next";

export const config = {
  enableSelector: "strict",
  fallbackLng: "en",
  supportedLngs: ["en", "id"],
  ns: ["common", "errors"] satisfies FlatNamespace[],
  defaultNS: "common",
  interpolation: { escapeValue: false },
} satisfies InitOptions;

export const COOKIE_LANGUAGE_KEY = "language";

3. Resources + type-safe keys

// src/lib/i18n/resources.ts
import commonEn from "@/../public/translations/en/common.json";
import commonId from "@/../public/translations/id/common.json";
// ...

export const resources = {
  en: {
    common: commonEn,
    // ...
  },
  id: {
    common: commonId,
    // ...
  },
} as const;

declare module "i18next" {
  interface CustomTypeOptions {
    enableSelector: "strict";
    defaultNS: "common";
    resources: (typeof resources)["en"];
  }
}

This file imports every locale JSON, but it's only used by the server utilities, and TanStack Start strips the server code (and this file with it) from the client bundle. So the full resource set never ships to the browser.

4. Client utilities

The client utilities initialize the instance, read the language preference, and write the cookie:

// src/lib/i18n/client.ts
import i18next, { type InitOptions } from "i18next";
import I18NextHttpBackend from "i18next-http-backend";
import { initReactI18next } from "react-i18next";
import pkg from "@/../package.json";
import { COOKIE_LANGUAGE_KEY, config } from "./config";

export function getClientInstance(language: string, overrideConfig?: InitOptions) {
  globalThis.__i18n ??= i18next.createInstance();
  const instance = globalThis.__i18n;
  if (instance.isInitialized) {
    return instance;
  }

  void instance
    .use(I18NextHttpBackend)
    .use(initReactI18next)
    .init({
      ...structuredClone(config),
      debug: import.meta.env.DEV,
      initAsync: false,
      partialBundledLanguages: true, // resources from SSR are bundled; load the rest lazily
      backend: {
        loadPath: `/translations/{{lng}}/{{ns}}.json?v=${pkg.version}`, // cache-bust per release
      },
      lng: language,
      ...overrideConfig,
    });

  instance.isInitialized = true;
  instance.initializedLanguageOnce = true;
  if (overrideConfig?.resources) {
    instance.initializedStoreOnce = true;
  }

  return instance;
}

export function getClientLanguage() {
  const languageFromCookie = document.cookie
    .split(";")
    .map((cookie) => cookie.trim())
    .find((cookie) => cookie.startsWith(`${COOKIE_LANGUAGE_KEY}=`))
    ?.split("=")[1];

  return [languageFromCookie || config.fallbackLng, !!languageFromCookie] as const;
}

export function setClientLanguageCookie(language: string) {
  document.cookie = `${COOKIE_LANGUAGE_KEY}=${language}; path=/; max-age=31536000`;
}

On the client we keep one shared global instance. partialBundledLanguages plus the HTTP backend lets us seed some resources and fetch the rest on demand, and the manual isInitialized flags make react-i18next treat the instance as ready right away so the first render doesn't suspend.

5. Server utilities

The server utilities mirror the client's responsibilities:

// src/lib/i18n/server.ts
import { setCookie } from "@tanstack/react-start/server";
import acceptLanguageParser from "accept-language-parser";
import i18next, { type InitOptions } from "i18next";
import { initReactI18next } from "react-i18next";
import { COOKIE_LANGUAGE_KEY, config } from "./config";
import { resources } from "./resources";

export function getServerInstance(language: string, overrideConfig?: InitOptions) {
  const instance = i18next.createInstance();
  void instance.use(initReactI18next).init({
    ...structuredClone(config),
    initAsync: false,
    resources, // all languages bundled on the server
    lng: language,
    ...overrideConfig,
  });

  instance.isInitialized = true;
  instance.initializedLanguageOnce = true;
  instance.initializedStoreOnce = true;

  return instance;
}

export function getServerLanguage(headers: Headers) {
  let language = config.fallbackLng;
  let shouldUpdateCookie = false;

  const languageFromCookie =
    headers
      .get("cookie")
      ?.split("; ")
      .find((row) => row.startsWith(`${COOKIE_LANGUAGE_KEY}=`))
      ?.split("=")[1] ?? null;

  const acceptLanguage = headers.get("accept-language");
  const languageFromHeader = acceptLanguage
    ? acceptLanguageParser.pick(config.supportedLngs, acceptLanguage)
    : null;

  const detectedLanguage = languageFromCookie ?? languageFromHeader;
  if (detectedLanguage && config.supportedLngs.includes(detectedLanguage)) {
    language = detectedLanguage;
  }

  if (language !== languageFromCookie) {
    shouldUpdateCookie = true;
  }

  return [language, shouldUpdateCookie] as const;
}

export function setServerLanguageCookie(language: string) {
  setCookie(COOKIE_LANGUAGE_KEY, language, { path: "/", maxAge: 365 * 24 * 60 * 60 });
}

On the server we create one instance per request, which gets passed down through context.

Notice the structuredClone in both files. i18next mutates the config while it runs (for example, it pushes loaded namespaces into options.ns). Since we reuse one config object, we clone it so each instance gets its own copy. Without that, namespaces loaded during one request would leak into later requests on the same server. structuredClone is the simplest option, but it throws if your config ever contains functions, so if you add things like a custom formatter, clone just the ns array instead.

6. Isomorphic utilities

Finally, tie the two sides together behind one import:

// src/lib/i18n/index.ts
import { createSerializationAdapter } from "@tanstack/react-router";
import { createIsomorphicFn } from "@tanstack/react-start";
import { getRequestHeaders } from "@tanstack/react-start/server";
import type { DefaultNamespace, FlatNamespace, i18n, TFunction } from "i18next";
import { getClientInstance, getClientLanguage, setClientLanguageCookie } from "./client";
import { getServerInstance, getServerLanguage, setServerLanguageCookie } from "./server";

export { config as i18nConfig } from "./config";

export const getI18nInstance = createIsomorphicFn()
  .client(getClientInstance)
  .server(getServerInstance);

export const getLanguage = createIsomorphicFn()
  .client(getClientLanguage)
  .server(() => {
    const headers = getRequestHeaders();
    return getServerLanguage(headers);
  });

export const setLanguageCookie = createIsomorphicFn()
  .client(setClientLanguageCookie)
  .server(setServerLanguageCookie);

// i18next instances aren't serializable. This adapter is a no-op that
// hands back the global client instance we already have.
export const i18nSerializationAdapter = createSerializationAdapter<i18n, undefined>({
  key: "i18n",
  test: (value): value is i18n =>
    typeof value === "object" && value !== null && "language" in value && "store" in value,
  toSerializable: () => {},
  fromSerializable: () => globalThis.__i18n!,
});

export async function getFixedT<NS extends FlatNamespace[] = [DefaultNamespace]>(
  instance: i18n,
  namespaces: NS,
): Promise<TFunction<NS>>;
export async function getFixedT<NS extends FlatNamespace[] = [DefaultNamespace]>(
  instance: i18n,
  language: string,
  namespaces: NS,
): Promise<TFunction<NS>>;
export async function getFixedT<NS extends FlatNamespace[] = [DefaultNamespace]>(
  instance: i18n,
  languageOrNamespaces: NS | string,
  maybeNamespaces?: NS,
): Promise<TFunction<NS>> {
  const language = maybeNamespaces ? (languageOrNamespaces as string) : instance.language;
  const namespaces = (maybeNamespaces ?? languageOrNamespaces) as NS;

  await instance.loadNamespaces(namespaces);
  return instance.getFixedT(language, namespaces);
}

Two pieces matter here. The serialization adapter exists because TanStack Start won't let you pass a non-serializable value (like an i18next instance) to the client, but we don't actually want to serialize it. So the adapter does nothing on the way out, and on the client it just returns the global instance we already created. getFixedT loads a namespace before returning a t function, which is what you want on the client where namespaces arrive lazily; on the server it's basically free since everything is bundled.

Wiring Up TanStack Start

1. Type augmentations

Augment the router types. We do this in router.tsx for convenience, but it can live anywhere in your project:

// src/router.tsx
import type { FlatNamespace, i18n } from "i18next";

export function getRouter() {
  // ...
}

declare module "@tanstack/react-router" {
  interface Register {
    router: ReturnType<typeof getRouter>;
    server: {
      requestContext: { i18n: i18n; updateLanguageCookie: boolean };
    };
  }

  interface StaticDataRouteOption {
    namespaces?: FlatNamespace[];
  }
}

requestContext types the object you hand to the server entry, and namespaces is what lets each route declare which translation namespaces it needs.

2. Start config

// src/start.ts
import { createStart } from "@tanstack/react-start";
import { i18nSerializationAdapter } from "./lib/i18n";

export const startInstance = createStart(() => ({
  defaultSsr: true,
  serializationAdapters: [i18nSerializationAdapter],
}));

3. Server entrypoint

Use a custom server entry to build the per-request instance and put it in the request context:

// src/server.tsx
import type { Register } from "@tanstack/react-router";
import { renderRouterToStream } from "@tanstack/react-router/ssr/server";
import {
  createStartHandler,
  defineHandlerCallback,
  StartServer,
} from "@tanstack/react-start/server";
import { createServerEntry } from "@tanstack/react-start/server-entry";
import { I18nextProvider } from "react-i18next";
import { getServerInstance, getServerLanguage } from "./lib/i18n/server";

const customHandler = defineHandlerCallback(async ({ request, router, responseHeaders }) => {
  const { i18n } = router.options.additionalContext
    .serverContext as Register["server"]["requestContext"];

  return renderRouterToStream({
    request,
    router,
    responseHeaders,
    children: (
      <I18nextProvider i18n={i18n}>
        <StartServer router={router} />
      </I18nextProvider>
    ),
  });
});
const fetch = createStartHandler(customHandler);

export default createServerEntry({
  async fetch(request) {
    const [language, shouldUpdateCookie] = getServerLanguage(request.headers);
    const i18n = getServerInstance(language);

    return fetch(request, {
      context: { i18n, updateLanguageCookie: shouldUpdateCookie },
    });
  },
});

The fetch handler runs for every request: it detects the language, builds the instance, and passes it down as serverContext. The custom handler then wraps StartServer in I18nextProvider so server-rendered components translate against that instance. We put the provider here, at the entry level rather than inside a route component, so error and not-found pages can translate too, since those render in place of your normal component tree.

4. Client entrypoint

Recover the instance on the client and hydrate:

// src/client.tsx
import { StartClient } from "@tanstack/react-start/client";
import { StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { I18nextProvider } from "react-i18next";
import { getClientInstance } from "./lib/i18n/client";

const i18nData = globalThis.__i18nData;
const i18n = getClientInstance(i18nData.language, {
  ns: i18nData.namespaces,
  resources: i18nData.resources,
});

hydrateRoot(
  document,
  <StrictMode>
    <I18nextProvider i18n={i18n}>
      <StartClient />
    </I18nextProvider>
  </StrictMode>,
);

We read what the server injected into window.__i18nData (set up in the next step) and build the client instance from it.

Passing ns here is important. Seeding resources puts the data into i18next, but i18next only treats namespaces you list in ns as already loaded. If you skip a seeded namespace, i18next fetches it again right after hydration and you get a flash. So list all of them.

5. The root route

The root route handles language resolution, redirects, and SSR serialization.

First, language resolution in beforeLoad:

beforeLoad: async ({ serverContext, location, preload }) => {
  let i18n: i18n;
  let language: string;
  let shouldUpdateCookie = false;

  if (serverContext) {
    // On the server, the instance comes from request context.
    i18n = serverContext.i18n;
    language = i18n.language;
    shouldUpdateCookie = serverContext.updateLanguageCookie;
  } else {
    // serverContext is absent on the client, so detect and recover the instance.
    const [_language, _shouldUpdateCookie] = getLanguage();
    language = _language;
    shouldUpdateCookie = _shouldUpdateCookie;
    i18n = getI18nInstance(language);
  }

  let pathname = location.pathname;
  const firstSegment = pathname.split("/").filter(Boolean)[0];

  // Redirect to a language-prefixed URL when the resolved language isn't the
  // fallback and the first path segment is missing or unsupported.
  if (
    (!firstSegment || !i18nConfig.supportedLngs.includes(firstSegment)) &&
    language !== i18nConfig.fallbackLng
  ) {
    pathname = `/${language}${pathname === "/" ? "" : pathname}`;
    const search = location.searchStr === "?" ? "" : location.searchStr;
    throw redirect({ to: pathname + search, replace: true });
  }

  // A supported language in the URL wins.
  if (firstSegment && i18nConfig.supportedLngs.includes(firstSegment)) {
    language = firstSegment;
    shouldUpdateCookie = true;
  }

  // Only run side effects on a real navigation, never during a preload.
  if (!preload) {
    if (i18n.language !== language) {
      await i18n.changeLanguage(language);
    }
    if (shouldUpdateCookie) {
      setLanguageCookie(language);
    }
  }

  return { i18n };
},

serverContext is the signal for which side you're on: it's there on the server and absent on the client. And the !preload guard keeps us from changing the language or writing cookies just because a link was hovered.

Next, the SSR serialization helper:

function getI18nDataScript(i18n: i18n, matches: AnyRouteMatch[]) {
  const language = i18n.language;
  const namespacesFromMatches = matches
    .filter((match) => !!match.staticData?.namespaces?.length)
    .flatMap((match) => match.staticData.namespaces!);
  const namespaces = new Set<FlatNamespace>([...i18nConfig.ns, ...namespacesFromMatches]);

  const i18nData: typeof globalThis.__i18nData = {
    language,
    namespaces: [...namespaces],
    resources: { [language]: {} },
  };

  for (const namespace of namespaces) {
    const resource = i18n.store.data?.[language]?.[namespace];
    if (resource) {
      i18nData.resources[language]![namespace] = resource;
    }
  }

  return `window.__i18nData = ${JSON.stringify(i18nData)}`;
}

declare global {
  var __i18n: i18n | undefined;
  var __i18nData: {
    language: string;
    namespaces: string[];
    resources: Resource;
  };
}

This collects only what the current page needs, the always-loaded i18nConfig.ns plus each matched route's staticData.namespaces, and serializes those for the active language. That's the selective loading in action: the home page ships home's namespaces and nothing else.

Finally, the shell component:

function RootDocument({ children }: { children: React.ReactNode }) {
  const { i18n } = useTranslation();
  const matches = useMatches();

  return (
    <html lang={i18n.language} dir={i18n.dir()}>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        {import.meta.env.SSR && (
          <ScriptOnce>{getI18nDataScript(i18n, matches)}</ScriptOnce>
        )}
        <Scripts />
      </body>
    </html>
  );
}

// ...
export const Route = createRootRoute({
  shellComponent: RootDocument,
  // ...
});

ScriptOnce renders a server-only inline script that removes itself after running, so it's gone before React hydrates and doesn't cause a mismatch. The import.meta.env.SSR guard is false in the client build, so the whole thing is dropped from the browser bundle. It's a server-only concern, so there's no reason to ship or run it on the client.

Using Translations

Declaring namespaces per route

A route declares the namespaces it needs through staticData. That's the only thing the SSR serializer reads to decide what to ship:

// src/routes/{-$lang}/index.tsx
export const Route = createFileRoute("/{-$lang}/")({
  staticData: { namespaces: ["home"] },
  component: Home,
});

function Home() {
  const { t } = useTranslation("home");
  return <h1>{t(($) => $.home.title)}</h1>;
}

Setting the page title

You can set the title in head and read the instance from match.context.i18n. Since head runs during the load phase, this sets the title and loads the namespace in one go, and you don't need to thread it through a loader:

head: async ({ match }) => {
  const t = await getFixedT(match.context.i18n, ["home"]);
  return { meta: [{ title: t(($) => $.home.title) }] };
},

Keep the route's staticData.namespaces either way, since that's what feeds the SSR payload.

A language switcher

When switching languages, load the target language before changing the URL:

// src/components/language-switcher.tsx
async function handleChangeLanguage(newLanguage: string) {
  // ...build the new pathname...
  await i18n.changeLanguage(newLanguage); // load the target language first
  setClientLanguageCookie(newLanguage);
  await router.navigate({ to: pathname + search, replace: true });
  await router.invalidate();
}

Error and not-found pages

Error and not-found pages need titles too, but head only runs during loading, so it can't title a page that throws while rendering. The simple, reliable approach is to render <title> inside the error component itself. React 19 moves it into <head>, and it works whether the failure happened at load time or render time:

// src/components/errors.tsx
function BaseError({ title, description }: { title: string; description: string }) {
  const { t, i18n } = useTranslation("common");
  return (
    <>
      <title>{title}</title>
      <div>
        <h1>{title}</h1>
        <p>{description}</p>
        <Link to="/{-$lang}" params={{ lang: i18n.language }}>
          {t(($) => $.common.links.home)}
        </Link>
      </div>
    </>
  );
}

Just don't set the error title in both head and a component <title>, or you'll end up with two of them.

Gotchas

A quick recap of the things that tend to trip people up:

Clone the config per instance. i18next mutates it as it runs, so a shared config leaks state between requests on the server.
List every seeded namespace in ns on the client. Otherwise i18next re-fetches them after hydration and you get a flash.
Put the provider at the entry level, not inside a component, so error and not-found pages can translate.

Wrap-up

You now have a TanStack Start i18n setup that detects language on the server, renders translated HTML, hydrates without a flash, loads namespaces selectively, and passes the instance across the boundary cleanly. Adapt the detection order, bundling granularity, and routing to taste. The full example is on GitHub if you want a starting point: https://github.com/ookamiiixd/tanstack-start-i18next

Good luck!

推荐订阅源

DEV Community

Table of Contents