Cómo implementar enrutamiento basado en localización 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 específicas de idioma, 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 manera clara de distinguir entre las variantes de idioma del mismo contenido.

Solución

Coloca un identificador de idioma directamente en la ruta 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 utilizar un parámetro de localización en la estructura de la ruta, cada URL se vuelve autodescriptiva y compartible, permitiendo a los usuarios marcar o compartir enlaces a contenido en su idioma preferido mientras se permite a los motores de búsqueda indexar correctamente cada variante de idioma.

Pasos

1. Crear una ruta de diseño de localización

Define un parámetro de localización opcional utilizando la sintaxis {-$locale} para crear patrones de enrutamiento flexibles donde el parámetro de localización es opcional. TanStack Start utiliza 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 (localización no definida) como con /en/about (localización es "en"), permitiéndote soportar URLs con o sin un prefijo de localización.

2. Crear rutas secundarias bajo el diseño de localización

TanStack Router utiliza enrutamiento anidado para hacer coincidir la URL con el árbol de componentes correcto para renderizar. Crea archivos de ruta como hijos del parámetro de localización para heredar la configuración regional desde 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 localización.

3. Acceder al parámetro de localización en los componentes

Utiliza el hook useParams para leer la localización 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 localización no está definido, el componente utiliza un idioma base por defecto, permitiendo que la aplicación maneje tanto URLs localizadas como no localizadas.

4. Crear enlaces que preserven la localización

Utiliza el componente Link con el parámetro de localización 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 la localización actual en la prop params, los enlaces generan automáticamente URLs que coinciden con el contexto de idioma del usuario, como /fr/about cuando se visualiza la versión en francés.