So validieren Sie Locale-Parameter in URLs in TanStack Start v1

Problem

Wenn Sprachcodes Teil der URL-Struktur werden, verwandeln sie sich in Benutzereingaben, die validiert werden müssen. Benutzer können manuell beliebige Zeichenfolgen in das Locale-Segment eingeben – /xx/about, /gibberish/contact oder /typo123/products – genauso einfach wie gültige Codes wie /en/about oder /fr/contact. Ohne Validierung könnte die Anwendung versuchen, Übersetzungen für nicht existierende Locales zu laden, fehlerhafte Inhalte anzuzeigen oder abzustürzen. Jede ungültige Locale stellt eine potenzielle Sackgasse dar, aus der Benutzer nicht wiederherstellen oder zu funktionierenden Seiten navigieren können.

Nicht validierte Locale-Parameter erzeugen unvorhersehbares Verhalten. Die Anwendung könnte stillschweigend keine Übersetzungen laden, eine Mischung aus Fallback- und fehlenden Inhalten rendern oder Laufzeitfehler werfen, wenn auf Übersetzungsschlüssel zugegriffen wird. Benutzer, die defekten Links folgen oder URLs falsch eingeben, erhalten kein klares Feedback darüber, was schiefgelaufen ist oder wie sie es beheben können.

Lösung

Validieren Sie den Locale-Parameter aus der URL gegen eine Liste unterstützter Locales in der beforeLoad-Funktion der Route. Wenn die Locale ungültig oder fehlend ist, leiten Sie den Benutzer zu einer gültigen URL mit der Standard-Locale um oder werfen Sie einen Not-Found-Fehler, um eine hilfreiche Fehlerseite anzuzeigen. Dies stellt sicher, dass nur unterstützte Locales verarbeitet werden und dass Benutzer immer auf einer gültigen, übersetzbaren Seite landen.

Die beforeLoad-Funktion wird ausgeführt, bevor die Route geladen wird, was sie zum idealen Ort macht, um die Locale zu überprüfen. Durch das Werfen eines redirect()- oder notFound()-Fehlers verhindern Sie, dass die Route mit einer ungültigen Locale gerendert wird, und führen Benutzer zu einem funktionierenden Zustand.

Schritte

1. Unterstützte Locales definieren

Erstellen Sie ein konstantes Array gültiger Locale-Codes und eine typsichere Validierungsfunktion.

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

Dies bietet eine einzige Quelle der Wahrheit für unterstützte Locales und eine wiederverwendbare Validierungsfunktion, die TypeScript verstehen kann.

2. Eine Layout-Route mit Locale-Validierung erstellen

Verwenden Sie einen optionalen Locale-Parameter und validieren Sie ihn in 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,
    };
  },
});

Die Funktion beforeLoad überprüft den Locale-Parameter. Falls er existiert, aber ungültig ist, wird der Benutzer zum selben Pfad ohne Locale-Präfix weitergeleitet, was zum Standard-Locale führt. Das validierte Locale wird im Kontext für untergeordnete Routen zurückgegeben.

3. Locale in verschachtelten Routen validieren

Für Routen, die ein Locale erfordern, validieren Sie es und werfen Sie notFound(), falls es ungültig ist.

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

Dieser Ansatz zeigt eine Not-Found-Seite für ungültige Locales anstelle einer Weiterleitung, was nützlich ist, wenn Sie signalisieren möchten, dass die URL fehlerhaft ist, anstatt sie stillschweigend zu korrigieren.

4. Eine Not-Found-Komponente für ungültige Locales hinzufügen

Definieren Sie eine notFoundComponent auf der Root-Route, um Fehler bei ungültigen Locales elegant zu behandeln.

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

Diese Komponente wird gerendert, wenn notFound() von beforeLoad geworfen wird und gibt Benutzern eine klare Nachricht sowie eine Möglichkeit, zurück zu einer gültigen Seite zu navigieren.