TanStack Router

Usa @better-translate/tanstack-router cuando tu app use TanStack Router o TanStack Start y quieras URLs con locale.

En la mayoría de apps reales lo combinarás con:

@better-translate/core para el traductor
@better-translate/react para hooks dentro de componentes React

1. Instalar los paquetes

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

2. Crear el traductor compartido

Crea 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. Añadir la configuración de enrutamiento por locale

Crea src/lib/routing.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. Crear helpers de navegación localizados

Crea 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});

Usa routeTemplate: "/$lang" o routeTemplate: "/{$lang}" para segmentos de locale obligatorios. Usa "/{-$lang}" cuando el locale por defecto deba omitir el segmento.

Los nombres de parámetro de locale admitidos vienen de @better-translate/core y se exponen aquí como SUPPORTED_TANSTACK_LOCALE_ROUTE_SYNTAXES más los subconjuntos obligatorio y opcional.

5. Envolver la app con el provider de React

Crea 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. Usar enlaces con locale y traducciones

Crea 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

Si usas TanStack Start, mantén la misma configuración de enrutamiento y navegación. Luego añade los helpers de servidor de @better-translate/tanstack-router/server igual que añadirías helpers de petición en Next.js.

Generar archivos de locale automáticamente

En lugar de escribir cada traducción a mano, usa la CLI para extraer cadenas y generar archivos de locale: Guía de la CLI

Ejemplos

tanstack-start-example