Adapters

Persist vs infer

Two chains, two jobs:

Persist = user choice (cookie, database). Infer = machine guess (Accept-Language).

Cookie adapter — anonymous visitors

Most marketing visitors are anonymous. When you omit adapters, persist defaults to [cookie()] — same as calling cookie() with no arguments:

import { cookie } from "@Wadiou/tanstack-i18n/adapters";

cookie()

Default cookie name is LOCALE (DEFAULT_COOKIE_NAME). Override only when needed:

cookie({ name: "MY_LOCALE" })

Read: server uses Cookie header; client uses document.cookie. Returns null if missing or not in locales.

Write: client uses Cookie Store API or document.cookie. Server does not call write directly — redirect/sync-cookie responses use serialize(locale) for Set-Cookie.

Tighten attributes for your domain:

cookie({
  path: "/",
  maxAge: 31536000,
  sameSite: "lax",
}),

Adapter id: cookie:LOCALE. Only one cookie() allowed in persist[].

localStorage adapter — client-only / SPA persistence

For Single Page Applications (SPAs) that do not use SSR, or where you want to store the selected language completely client-side in the browser:

import { localStorage } from "@Wadiou/tanstack-i18n/adapters";

localStorage()

Default key is LOCALE (DEFAULT_LOCAL_STORAGE_KEY). Override if needed:

localStorage({ key: "MY_LOCALE" })

• Read: Reads from window.localStorage. If a stored value exists and matches one of the supported locales, it returns it; otherwise, returns null.
• Write: Writes the active locale to window.localStorage.

Because localStorage is not sent with HTTP requests, it is ideal for pure client-side SPA setups (e.g. using TanStack React Router without TanStack Start). If you ever need to support SSR or server fallback in the future, you can also combine localStorage and cookie (the adapter is built to safely return null and no-op on the server without crashing):

adapters: {
  persist: [
    localStorage({ key: "LOCALE" }),
    cookie({ name: "LOCALE" }),
  ],
}

In this setup, localStorage is checked first on the client. If it returns null (e.g., during server-side rendering or on first load), the runtime falls back to the cookie adapter.

Accept-Language — first visit to /

A visitor lands on / with no cookie. The server entry runs infer:

infer: [acceptLanguage()],

The adapter parses Accept-Language, picks the best match from locales, or returns null. Combined with firstVisit.mode: "redirect", they may redirect to /ar/ before any cookie exists.

This does not run on subsequent getLocale() calls — only the server entry first-visit path (TanStack Start).

serverFn — logged-in account locale

When the marketing site adds accounts, store locale in session/DB:

import { serverFn } from "@Wadiou/tanstack-i18n/adapters";

serverFn({
  read: async (ctx) => {
    if (!ctx.request) return null;
    return getLocaleFromSession(ctx.request);
  },
  write: async (locale, ctx) => {
    await saveLocaleToSession(locale, ctx.request);
  },
}),

PersistRunContext supplies runtime, pathname, locales, defaultLocale, request, cookieHeader.

Client read always returns null — client resolution uses cookie or URL. Server reads power SSR and the server entry.

Order adapters — DB before cookie

Read: first adapter returning non-null wins.

Write: changeLocale() writes all persist adapters.

adapters: {
  persist: [
    serverFn({ read: fromDb, write: toDb }),
    cookie({ name: "LOCALE" }),
  ],
  infer: [acceptLanguage()],
},

Logged-in users resolve from DB; anonymous users fall through to cookie. Duplicate adapter ids fail at bind time.