Cómo implementar enrutamiento basado en locale en TanStack Start v1

Problema

Al construir una aplicación multilingüe, una decisión fundamental da forma a todo lo demás: ¿cómo sabrá la aplicación qué idioma mostrar? Sin un mecanismo explícito, la URL /about se vuelve ambigua: podría representar contenido en cualquier idioma. Los usuarios no pueden compartir enlaces a versiones en idiomas específicos, y los motores de búsqueda tienen dificultades para entender qué versión pertenece a qué audiencia. Esta ambigüedad crea problemas tanto para la experiencia del usuario como para el SEO, ya que no hay una forma clara de distinguir entre variantes de idioma del mismo contenido.

Solución

Coloca un identificador de idioma directamente en la ruta de la URL, como /en/about o /fr/about. Esto hace que cada ruta sea única para un idioma específico, eliminando la ambigüedad tanto para usuarios como para motores de búsqueda. Al usar un parámetro de locale en la estructura de rutas, cada URL se vuelve autodescriptiva y compartible, permitiendo a los usuarios marcar o compartir enlaces a contenido en su idioma preferido mientras permite a los motores de búsqueda indexar correctamente cada variante de idioma.

Pasos

1. Crear una ruta de layout de locale

Define un parámetro de locale opcional usando la sintaxis {-$locale} para crear patrones de enrutamiento flexibles donde el parámetro de locale es opcional. TanStack Start usa enrutamiento basado en archivos donde las rutas se definen en el directorio src/routes.

import { createFileRoute, Outlet } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}")({
  component: LocaleLayout,
});

function LocaleLayout() {
  return <Outlet />;
}

Esta ruta coincide tanto con /about (locale es undefined) como con /en/about (locale es "en"), permitiéndote soportar URLs con o sin prefijo de locale.

2. Crear rutas hijas bajo el layout de locale

TanStack Router usa enrutamiento anidado para hacer coincidir la URL con el árbol de componentes correcto a renderizar. Crea archivos de ruta como hijos del parámetro de locale para heredar el locale de la URL.

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}/about")({
  component: AboutPage,
});

function AboutPage() {
  const { locale } = Route.useParams();
  const currentLocale = locale || "en";

  return (
    <div>
      <h1>About Us</h1>
      <p>Current locale: {currentLocale}</p>
    </div>
  );
}

La estructura de archivos de ruta {-$locale}/about.tsx crea rutas como /about y /en/about que ambas renderizan el mismo componente con acceso al parámetro de locale.

3. Accede al parámetro de locale en los componentes

Utiliza el hook useParams para leer el locale desde la URL y determinar qué idioma mostrar.

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}/products")({
  component: ProductsPage,
});

function ProductsPage() {
  const { locale } = Route.useParams();
  const displayLocale = locale || "en";

  return (
    <div>
      <h1>{displayLocale === "fr" ? "Produits" : "Products"}</h1>
    </div>
  );
}

Cuando el parámetro de locale no está definido, el componente utiliza por defecto un idioma base, lo que permite que la aplicación maneje tanto URLs localizadas como no localizadas.

4. Crea enlaces que preserven el locale

Utiliza el componente Link con el parámetro de locale para navegar entre páginas manteniendo el idioma actual.

import { Link, createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}/")({
  component: HomePage,
});

function HomePage() {
  const { locale } = Route.useParams();

  return (
    <nav>
      <Link to="/{-$locale}/about" params={{ locale }}>
        About
      </Link>
      <Link to="/{-$locale}/products" params={{ locale }}>
        Products
      </Link>
    </nav>
  );
}

Al pasar el locale actual en la prop params, los enlaces generan automáticamente URLs que coinciden con el contexto de idioma actual del usuario, como /fr/about al visualizar la versión en francés.