Wie man Locale-Parameter in URLs in TanStack Start v1 validiert

Problem

Wenn Sprachcodes Teil der URL-Struktur werden, verwandeln sie sich in Benutzereingaben, die validiert werden müssen. Benutzer können manuell jeden beliebigen String 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 abstürzen. Jede ungültige Locale stellt eine potenzielle Sackgasse dar, aus der Benutzer nicht zu funktionierenden Seiten navigieren können.

Nicht validierte Locale-Parameter erzeugen unvorhersehbares Verhalten. Die Anwendung könnte stillschweigend beim Laden von Übersetzungen scheitern, eine Mischung aus Fallback- und fehlenden Inhalten rendern oder Laufzeitfehler werfen, wenn auf Übersetzungsschlüssel zugegriffen wird. Benutzer, die fehlerhaften Links folgen oder URLs falsch eingeben, erhalten keine klare Rückmeldung 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 nicht vorhanden ist, leiten Sie den Benutzer zu einer gültigen URL mit der Standard-Locale weiter 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. Erstellen Sie eine Layout-Route mit Locale-Validierung

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. Wenn er existiert, aber ungültig ist, wird der Benutzer zum selben Pfad ohne das Locale-Präfix umgeleitet, was zur Standardsprache führt. Die validierte Locale wird im Kontext zurückgegeben, damit untergeordnete Routen sie verwenden können.

3. Validieren Sie die Locale in verschachtelten Routen

Für Routen, die eine Locale erfordern, validieren Sie diese und werfen Sie notFound(), wenn sie 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 anstatt umzuleiten, was nützlich ist, wenn Sie signalisieren möchten, dass die URL fehlerhaft ist, anstatt sie stillschweigend zu korrigieren.

4. Fügen Sie eine Not-Found-Komponente für ungültige Locales hinzu

Definieren Sie eine notFoundComponent auf der Root-Route, um ungültige Locale-Fehler 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 den Benutzern eine klare Nachricht und eine Möglichkeit, zu einer gültigen Seite zu navigieren.