Get started

Get started with TanStack i18n. Install the library, configure your locale runtime, and learn the architectural boundaries for message translations.

Install the package and wire locale routing in TanStack Start or Router. For full scope, see the home page.

AI Agent Integration

We provide consolidated text indexes and raw Markdown routes optimized for LLMs and AI coding assistants. See AI Integration for instructions on how to use these endpoints.

Install

pnpm add @Wadiou/tanstack-i18n

npm install @Wadiou/tanstack-i18n

yarn add @Wadiou/tanstack-i18n

bun add @Wadiou/tanstack-i18n

The core package gives you locale config and runtime. Add subpaths for the stack you actually use:

React + TanStack Start and Router — @Wadiou/tanstack-i18n/react for a locale provider, plus @Wadiou/tanstack-i18n/react-router and @Wadiou/tanstack-i18n/react-start when you wire routing and the server entry.
Solid — @Wadiou/tanstack-i18n/solid with @Wadiou/tanstack-i18n/solid-router and @Wadiou/tanstack-i18n/solid-start for the same roles.

You do not need every subpath on day one. Export and peer details are in Exports and peers.

Define config and runtime

Create your locale config with defineLocaleConfig — locales, URL prefix mode, and adapters.

Bind it with createLocaleRuntime and export the runtime for your app.

import {
  defineLocaleConfig,
  createLocaleRuntime,
} from "@Wadiou/tanstack-i18n";
import { acceptLanguage } from "@Wadiou/tanstack-i18n/adapters";

const config = defineLocaleConfig({
  locales: ["en", "ar"],
  defaultLocale: "en",
  adapters: {
    infer: [acceptLanguage()],
  },
});

export const locale = createLocaleRuntime(config);

Wire your stack — guided journey

The Guides section walks one bilingual marketing site (en, ar) from config to language switcher. Follow in sidebar order:

Configuration — build defineLocaleConfig step by step
URL prefix modes — always, as-needed, never
Locale runtime — bind createLocaleRuntime
Adapters — cookie, infer, ordering
TanStack Start — server entry wrapper
TanStack Router — localized routes and links
Change locale — switcher + provider

Runtime overview

createLocaleRuntime returns a LocaleRuntime. Full method reference, examples, and getRequest: Locale runtime.

Method	Role
`config`	Your `LocaleConfig` from `defineLocaleConfig`
`getLocale()`	Active locale — URL segment, then persist adapters, then `defaultLocale`
`localizeUrl()` / `deLocalizeUrl()`	Add or strip locale segments in pathnames
`createServerEntry()`	TanStack Start request handler — Behavior contract

User-initiated locale switching belongs in React or Solid via setLocale from Change locale — not by calling the runtime directly from app UI.

On React or Solid, use createLocaleProvider — Change locale.

Locale vs messages

Concern	TanStack i18n	Translation library
Locale in URL	Yes	No
Redirects, cookies, first visit	Yes	No
Message catalogs, `t()`, formatting	No	Yes
Language switcher + router navigation	Yes	Via `setLocale` from Change locale

Pair this package with any catalog / formatting library. Common choices include use-intl, Paraglide, and react-intl. We document use-intl first as the primary integration example — full step-by-step guide: use-intl.

What's next

Start the guided journey at Configuration — each guide extends the same marketing site example. Then wire messages in use-intl. API lookup: Exports and peers and Behavior contract.