Cómo mantener la localización en los enlaces de navegación en TanStack Start v1

Problema

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

Sin un enfoque sistemático para la navegación con reconocimiento de localización, los desarrolladores se enfrentan a elegir entre enlazar manualmente la localización a través de cada componente Link o aceptar que los usuarios serán cambiados inesperadamente al idioma predeterminado durante la sesión. Ambos resultados degradan la experiencia del usuario y aumentan la carga de mantenimiento.

Solución

Crear un componente envoltorio alrededor del Link del framework que automáticamente lea la localización actual desde la URL y la 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 de reconocimiento de localización sin requerir que los desarrolladores pasen manualmente parámetros de localización en cada punto de llamada.

Este enfoque funciona leyendo la localización activa desde los parámetros de ruta utilizando los hooks del router, y luego fusionando esa localización en los parámetros del enlace de destino. El envoltorio preserva toda la funcionalidad de Link mientras asegura la continuidad de localización a través de la navegación.

Pasos

1. Crear un componente envoltorio Link con reconocimiento de localización

Construir un componente que lea la localización actual y automáticamente la incluya 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 la locale actual, y la fusiona en la prop params pasada al Link subyacente. El operador spread asegura que cualquier parámetro proporcionado explícitamente tenga precedencia.

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

Reemplaza los componentes estándar Link 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 localización se conserva sin intervención manual en cada sitio de enlace.

3. Maneja el cambio de localización explícitamente cuando sea necesario

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

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 un control explícito sobre el parámetro de localización, 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.