Comment implémenter le routage basé sur la locale dans TanStack Start v1

Problème

Lors de la création d'une application multilingue, une décision fondamentale façonne tout le reste : comment l'application saura-t-elle quelle langue afficher ? Sans mécanisme explicite, l'URL /about devient ambiguë—elle pourrait représenter du contenu dans n'importe quelle langue. Les utilisateurs ne peuvent pas partager de liens vers des versions linguistiques spécifiques, et les moteurs de recherche ont du mal à comprendre quelle version appartient à quel public. Cette ambiguïté crée des problèmes tant pour l'expérience utilisateur que pour le référencement, car il n'existe aucun moyen clair de distinguer les variantes linguistiques d'un même contenu.

Solution

Placez un identifiant de langue directement dans le chemin de l'URL, tel que /en/about ou /fr/about. Cela rend chaque chemin unique à une langue spécifique, éliminant l'ambiguïté tant pour les utilisateurs que pour les moteurs de recherche. En utilisant un paramètre de locale dans la structure de routage, chaque URL devient auto-descriptive et partageable, permettant aux utilisateurs de mettre en favoris ou de partager des liens vers du contenu dans leur langue préférée tout en permettant aux moteurs de recherche d'indexer correctement chaque variante linguistique.

Étapes

1. Créer une route de layout de locale

Définissez un paramètre de locale optionnel en utilisant la syntaxe {-$locale} pour créer des modèles de routage flexibles où le paramètre de locale est optionnel. TanStack Start utilise un routage basé sur les fichiers où les routes sont définies dans le répertoire src/routes.

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

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

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

Cette route correspond à la fois à /about (la locale est undefined) et à /en/about (la locale est "en"), vous permettant de prendre en charge des URL avec ou sans préfixe de locale.

2. Créer des routes enfants sous la mise en page de locale

TanStack Router utilise le routage imbriqué pour faire correspondre l'URL avec l'arborescence de composants correcte à afficher. Créez des fichiers de route en tant qu'enfants du paramètre de locale pour hériter de la locale depuis l'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 structure de fichiers de route {-$locale}/about.tsx crée des chemins comme /about et /en/about qui affichent tous deux le même composant avec accès au paramètre de locale.

3. Accéder au paramètre de locale dans les composants

Utilisez le hook useParams pour lire la locale depuis l'URL et déterminer quelle langue afficher.

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

Lorsque le paramètre de locale n'est pas défini, le composant utilise par défaut une langue de base, permettant à l'application de gérer à la fois les URL localisées et non localisées.

4. Créer des liens qui préservent la locale

Utilisez le composant Link avec le paramètre de locale pour naviguer entre les pages tout en conservant la langue actuelle.

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

En passant la locale actuelle dans la prop params, les liens génèrent automatiquement des URL qui correspondent au contexte linguistique actuel de l'utilisateur, comme /fr/about lors de la consultation de la version française.