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:

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:

1import { defineRouting } from "@better-translate/tanstack-router";23export const routing = defineRouting({4  defaultLocale: "en",5  locales: ["en", "es"] as const,6  routeTemplate: "/$lang",7});

Create src/lib/navigation.tsx:

tsx

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

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