Comment valider les paramètres de locale dans les URL avec TanStack Start v1

Problème

Lorsque les codes de langue font partie de la structure de l'URL, ils se transforment en entrée utilisateur qui doit être validée. Les utilisateurs peuvent saisir manuellement n'importe quelle chaîne dans le segment de locale — /xx/about, /gibberish/contact ou /typo123/products — aussi facilement que des codes valides comme /en/about ou /fr/contact. Sans validation, l'application peut tenter de charger des traductions pour des locales inexistantes, afficher du contenu cassé ou planter. Chaque locale invalide représente une impasse potentielle où les utilisateurs ne peuvent ni récupérer ni naviguer vers des pages fonctionnelles.

Les paramètres de locale non validés créent un comportement imprévisible. L'application peut échouer silencieusement à charger les traductions, afficher un mélange de contenu de secours et de contenu manquant, ou générer des erreurs d'exécution lors de l'accès aux clés de traduction. Les utilisateurs qui suivent des liens cassés ou font des fautes de frappe dans les URL se retrouvent sans retour clair sur ce qui s'est mal passé ou comment corriger le problème.

Solution

Validez le paramètre de locale de l'URL par rapport à une liste de locales prises en charge dans la fonction beforeLoad de la route. Lorsque la locale est invalide ou manquante, redirigez l'utilisateur vers une URL valide avec la locale par défaut ou levez une erreur de type « non trouvé » pour afficher une page d'erreur utile. Cela garantit que seules les locales prises en charge sont traitées et que les utilisateurs arrivent toujours sur une page valide et traduisible.

La fonction beforeLoad s'exécute avant le chargement de la route, ce qui en fait l'endroit idéal pour vérifier la locale. En levant une erreur redirect() ou notFound(), vous empêchez le rendu de la route avec une locale invalide et guidez les utilisateurs vers un état fonctionnel.

Étapes

1. Définir les locales prises en charge

Créez un tableau constant de codes de locale valides et une fonction de validation type-safe.

const SUPPORTED_LOCALES = ["en", "fr", "es", "de"] as const;

type Locale = (typeof SUPPORTED_LOCALES)[number];

function isValidLocale(locale: string | undefined): locale is Locale {
  return SUPPORTED_LOCALES.includes(locale as Locale);
}

Cela fournit une source unique de vérité pour les locales prises en charge et une fonction de validation réutilisable que TypeScript peut comprendre.

2. Créer une route de layout avec validation de locale

Utilisez un paramètre de locale optionnel et validez-le dans beforeLoad.

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

const DEFAULT_LOCALE: Locale = "en";

export const Route = createFileRoute("/{-$locale}")({
  beforeLoad: ({ params }) => {
    const { locale } = params;

    if (locale && !isValidLocale(locale)) {
      throw redirect({
        to: "/{-$locale}",
        params: { locale: undefined },
        replace: true,
      });
    }

    return {
      locale: (locale as Locale) || DEFAULT_LOCALE,
    };
  },
});

La fonction beforeLoad vérifie le paramètre de locale. S'il existe mais est invalide, l'utilisateur est redirigé vers le même chemin sans le préfixe de locale, qui se résout à la locale par défaut. La locale validée est retournée dans le contexte pour être utilisée par les routes enfants.

3. Valider la locale dans les routes imbriquées

Pour les routes qui nécessitent une locale, validez-la et lancez notFound() si elle est invalide.

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

export const Route = createFileRoute("/{-$locale}/products")({
  beforeLoad: ({ params }) => {
    const { locale } = params;

    if (locale && !isValidLocale(locale)) {
      throw notFound();
    }

    return {
      locale: (locale as Locale) || DEFAULT_LOCALE,
    };
  },
  component: ProductsPage,
});

function ProductsPage() {
  const { locale } = Route.useRouteContext();
  return <div>Products in {locale}</div>;
}

Cette approche affiche une page introuvable pour les locales invalides au lieu de rediriger, ce qui est utile lorsque vous souhaitez signaler que l'URL est mal formée plutôt que de la corriger silencieusement.

4. Ajouter un composant introuvable pour les locales invalides

Définissez un notFoundComponent sur la route racine pour gérer les erreurs de locale invalide de manière élégante.

import { createRootRoute } from "@tanstack/react-router";

export const Route = createRootRoute({
  notFoundComponent: () => {
    return (
      <div>
        <h1>Page Not Found</h1>
        <p>The language or page you requested does not exist.</p>
        <a href="/">Go to home page</a>
      </div>
    );
  },
});

Ce composant s'affiche lorsque notFound() est lancé depuis beforeLoad, donnant aux utilisateurs un message clair et un moyen de naviguer vers une page valide.