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 d'URL, ils deviennent des entrées utilisateur qui doivent être validées. 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 défectueux ou planter. Chaque locale invalide représente une impasse potentielle où les utilisateurs ne peuvent pas récupérer ou naviguer vers des pages fonctionnelles.

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

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 lancez une erreur "not-found" pour afficher une page d'erreur utile. Cela garantit que seules les locales prises en charge sont traitées et que les utilisateurs atterrissent 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 lançant une erreur redirect() ou notFound(), vous empêchez la route de s'afficher 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 typée.

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 mise en page 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 n'est pas valide, l'utilisateur est redirigé vers le même chemin sans le préfixe de locale, ce qui résout vers 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 n'est pas valide.

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 non trouvée pour les locales invalides au lieu de rediriger, ce qui est utile lorsque vous voulez signaler que l'URL est mal formée plutôt que de la corriger silencieusement.

4. Ajouter un composant not-found pour les locales invalides

Définissez un notFoundComponent sur la route racine pour gérer élégamment les erreurs de locale invalide.

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.