Better TranslateHome
GitHub
Getting Started
  • Introduction
  • Mission
  • Installation
  • CLI
  • Skills
  • RTL
  • Changelog
Adapters
  • Core
  • React
  • Expo
  • Astro
  • MD & MDX
  • Next.js
  • TanStack Router

TanStack Router

Use @better-translate/tanstack-router when your app uses TanStack Router or TanStack Start and you want locale-aware URLs.

In most real apps you will pair it with:

  • @better-translate/core for the translator
  • @better-translate/react for hooks inside React components

1. Install the packages

npm install @better-translate/core @better-translate/react @better-translate/tanstack-router

2. Create the shared translator

Create src/lib/i18n.ts:

ts
1import { configureTranslations } from "@better-translate/core";23const en = {4  home: {5    title: "Hello from TanStack Router",6  },7} as const;89const es = {10  home: {11    title: "Hola desde TanStack Router",12  },13} as const;1415export const translator = await configureTranslations({16  availableLocales: ["en", "es"] as const,17  defaultLocale: "en",18  fallbackLocale: "en",19  messages: { en, es },20});

3. Add the locale routing config

Create src/lib/routing.ts:

ts
1import {2  defineRouting,3  SUPPORTED_TANSTACK_LOCALE_ROUTE_SYNTAXES,4} from "@better-translate/tanstack-router";56export const routing = defineRouting({7  defaultLocale: "en",8  locales: ["en", "es"] as const,9  routeTemplate: "/$lang",10});1112console.log(SUPPORTED_TANSTACK_LOCALE_ROUTE_SYNTAXES);

4. Create localized navigation helpers

Create src/lib/navigation.tsx:

tsx
1import {2  Link,3  useLocation,4  useNavigate,5  useRouter,6} from "@tanstack/react-router";78import { createNavigationFunctions } from "@better-translate/tanstack-router/navigation";910import { routing } from "./routing";1112export const {13  Link: I18nLink,14  useLocale,15  useNavigate: useI18nNavigate,16  usePathname: useI18nPathname,17} = createNavigationFunctions({18  Link,19  routing,20  useLocation,21  useNavigate,22  useRouter,23});

Use routeTemplate: "/$lang" or routeTemplate: "/{$lang}" for required locale segments. Use "/{-$lang}" when the default locale should omit the segment.

Supported locale param names come from @better-translate/core and are exposed here as SUPPORTED_TANSTACK_LOCALE_ROUTE_SYNTAXES plus the required and optional subsets.

5. Wrap the app with the React provider

Create src/app.tsx:

tsx
1import { RouterProvider } from "@tanstack/react-router";23import { BetterTranslateProvider } from "@better-translate/react";45import { router } from "./router";6import { translator } from "./lib/i18n";78export function App() {9  return (10    <BetterTranslateProvider translator={translator}>11      <RouterProvider router={router} />12    </BetterTranslateProvider>13  );14}

6. Use locale-aware links and translations

Create src/components/header.tsx:

tsx
1import { useTranslations } from "@better-translate/react";23import { translator } from "../lib/i18n";4import { I18nLink, useLocale } from "../lib/navigation";56export function Header() {7  const currentLocale = useLocale();8  const { t } = useTranslations<typeof translator>();910  return (11    <header>12      <h1>{t("home.title")}</h1>13      <I18nLink to="/" params={{ lang: currentLocale }}>14        Home15      </I18nLink>16    </header>17  );18}

TanStack Start

If you are using TanStack Start, keep the same routing and navigation setup. Then add the server helpers from @better-translate/tanstack-router/server the same way you would add request helpers in Next.js.

Generate locale files automatically

Instead of writing every translation by hand, use the CLI to extract strings and generate locale files: CLI guide

Examples

  • tanstack-start-example