Comment maintenir la locale dans les liens de navigation dans TanStack Start v1

Problème

Lorsque l'information de locale est encodée dans le chemin de l'URL, chaque lien de navigation doit préserver cette locale pour maintenir une expérience utilisateur cohérente. Si un utilisateur navigue sur la version française d'un site à l'adresse /fr/products, cliquer sur un lien vers /about le fait basculer vers la langue par défaut, rompant le contexte de sa session. Coder en dur les paramètres de locale dans chaque lien est répétitif et source d'erreurs, surtout à mesure que l'application grandit et que davantage de liens sont ajoutés dans les composants.

Sans approche systématique pour une navigation tenant compte de la locale, les développeurs font face à un choix entre passer manuellement la locale à travers chaque composant Link ou accepter que les utilisateurs soient basculés de manière inattendue vers la langue par défaut en pleine session. Ces deux résultats dégradent l'expérience utilisateur et augmentent la charge de maintenance.

Solution

Créer un composant wrapper autour du Link du framework qui lit automatiquement la locale actuelle depuis l'URL et l'injecte dans la prop params de chaque cible de navigation. En centralisant cette logique dans un seul composant réutilisable, tous les liens internes héritent d'un comportement tenant compte de la locale sans que les développeurs aient besoin de passer manuellement les paramètres de locale à chaque utilisation.

Cette approche fonctionne en lisant la locale active depuis les paramètres de route à l'aide des hooks du routeur, puis en fusionnant cette locale dans les paramètres du lien de destination. Le wrapper préserve toutes les autres fonctionnalités du Link tout en garantissant la continuité de la locale lors de la navigation.

Étapes

1. Créer un composant wrapper Link tenant compte de la locale

Construire un composant qui lit la locale actuelle et l'inclut automatiquement dans les paramètres de navigation.

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} />;
}

Ce composant utilise useParams avec strict: false pour accéder aux paramètres de n'importe quelle route dans l'application, extrait le locale actuel et le fusionne dans la prop params transmise au Link sous-jacent. L'opérateur de décomposition garantit que tous les paramètres fournis explicitement ont la priorité.

Remplacez les composants Link standard par LocaleLink dans toute votre application.

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

Lorsqu'un utilisateur visite /fr/products, tous les composants LocaleLink se résolvent automatiquement en /fr/about, /fr/contact et /fr/products/123. Le paramètre de locale est préservé sans intervention manuelle à chaque emplacement de lien.

3. Gérer le changement de locale explicitement si nécessaire

Pour les composants de sélecteur de langue, contournez l'injection automatique de locale en utilisant directement le Link standard.

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