Cómo mantener el idioma en los enlaces de navegación en TanStack Start v1

Problema

Cuando la información del idioma está codificada en la ruta de la URL, cada enlace de navegación debe preservar ese idioma para mantener una experiencia de usuario consistente. Si un usuario navega por la versión francesa de un sitio en /fr/products, hacer clic en un enlace a /about lo lleva al idioma predeterminado, rompiendo el contexto de su sesión. Codificar manualmente los parámetros de idioma en cada enlace es repetitivo y propenso a errores, especialmente a medida que la aplicación crece y se agregan más enlaces en los componentes.

Sin un enfoque sistemático para la navegación consciente del idioma, los desarrolladores se enfrentan a una elección entre pasar manualmente el idioma a través de cada componente Link o aceptar que los usuarios cambiarán inesperadamente al idioma predeterminado en medio de la sesión. Ambos resultados degradan la experiencia del usuario y aumentan la carga de mantenimiento.

Solución

Crear un componente envolvente alrededor del Link del framework que lea automáticamente el idioma actual de la URL y lo inyecte en la prop params de cada destino de navegación. Al centralizar esta lógica en un único componente reutilizable, todos los enlaces internos heredan el comportamiento consciente del idioma sin requerir que los desarrolladores pasen manualmente los parámetros de idioma en cada punto de uso.

Este enfoque funciona leyendo el idioma activo de los parámetros de ruta usando los hooks del router, luego fusionando ese idioma en los parámetros del enlace de destino. El envolvente preserva toda la funcionalidad de Link mientras asegura la continuidad del idioma en la navegación.

Pasos

1. Crear un componente envolvente de Link consciente del idioma

Construir un componente que lea el idioma actual y lo incluya automáticamente en los parámetros de navegación.

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

type LocaleLinkProps = LinkProps & {
  to: string;
};

export function LocaleLink(props: LocaleLinkProps) {
  const params = useParams({ strict: false });
  const currentLocale = params.locale;

  const enhancedParams = {
    ...props.params,
    ...(currentLocale && { locale: currentLocale }),
  };

  return <Link {...props} params={enhancedParams} />;
}

Este componente utiliza useParams con strict: false para acceder a los parámetros desde cualquier ruta en la aplicación, extrae el locale actual y lo fusiona en la prop params pasada al Link subyacente. El operador de propagación garantiza que cualquier parámetro proporcionado explícitamente tenga prioridad.

2. Usa el componente LocaleLink para la navegación interna

Reemplaza los componentes Link estándar con LocaleLink en toda tu aplicación.

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

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

function ProductsPage() {
  return (
    <div>
      <h1>Products</h1>
      <nav>
        <LocaleLink to="/{-$locale}/about">About</LocaleLink>
        <LocaleLink to="/{-$locale}/contact">Contact</LocaleLink>
        <LocaleLink to="/{-$locale}/products/$id" params={{ id: "123" }}>
          Product 123
        </LocaleLink>
      </nav>
    </div>
  );
}

Cuando un usuario visita /fr/products, todos los componentes LocaleLink se resuelven automáticamente a /fr/about, /fr/contact y /fr/products/123. El parámetro de idioma se conserva sin intervención manual en cada sitio de enlace.

3. Gestiona el cambio de idioma explícitamente cuando sea necesario

Para los componentes de selector de idioma, omite la inyección automática de idioma utilizando el Link estándar directamente.

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

export function LanguageSwitcher() {
  const params = useParams({ strict: false });
  const currentPath = window.location.pathname.replace(/^\/(en|fr|es)/, "");

  return (
    <div>
      <Link to={`/{-$locale}${currentPath}`} params={{ locale: "en" }}>
        English
      </Link>
      <Link to={`/{-$locale}${currentPath}`} params={{ locale: "fr" }}>
        Français
      </Link>
      <Link to={`/{-$locale}${currentPath}`} params={{ locale: "es" }}>
        Español
      </Link>
    </div>
  );
}

Los selectores de idioma requieren control explícito sobre el parámetro de idioma, por lo que utilizan el componente Link estándar y establecen explícitamente el parámetro locale. Esto permite a los usuarios cambiar de idioma mientras permanecen en la misma página lógica.