So validieren Sie Locale-Parameter in URLs in React Router v7

Problem

Wenn Locale-Identifikatoren Teil der URL-Struktur werden, verwandeln sie sich in Benutzereingaben, die beliebige Werte enthalten können. Ein Benutzer könnte manuell /xx/about, /gibberish/contact oder einen anderen ungültigen Locale-Code in die Adressleiste eingeben. Ohne Validierung muss die Anwendung entscheiden, wie diese ungültigen Eingaben behandelt werden. Wenn ungültige Locales zugelassen werden, kann dies zu fehlenden Übersetzungen, fehlerhafter Formatierung oder Laufzeitfehlern führen, wenn i18n-Bibliotheken versuchen, nicht vorhandene Locale-Daten zu laden. Ein stilles Zurückfallen auf eine Standard-Locale ohne Benachrichtigung des Benutzers führt zu Verwirrung darüber, welche Sprache angezeigt wird. Die Anzeige von Error Boundaries oder leeren Seiten lässt Benutzer ohne klaren Weg nach vorne zurück.

Die Herausforderung wird dadurch verstärkt, dass die Locale-Validierung früh im Request-Lifecycle erfolgen muss, bevor Komponenten gerendert werden und bevor Übersetzungsdaten geladen werden. Wenn die Validierung zu spät erfolgt, hat die Anwendung möglicherweise bereits versucht, locale-spezifische Ressourcen abzurufen oder i18n-Provider mit ungültiger Konfiguration zu initialisieren, was Ressourcen verschwendet und möglicherweise kaskadierende Fehler verursacht.

Lösung

Validieren Sie den Locale-Parameter in einem Route-Loader, bevor die Seite gerendert wird. Loader in React Router werden ausgeführt, bevor Komponenten gemountet werden, was sie zum idealen Ort macht, um zu prüfen, ob die angeforderte Locale in der Liste der unterstützten Sprachen Ihrer Anwendung vorhanden ist. Wenn die Locale gültig ist, lassen Sie die Anfrage normal fortfahren. Wenn die Locale ungültig ist, leiten Sie den Benutzer sofort zu einem sicheren Fallback um – entweder zum selben Pfad mit einer gültigen Standard-Locale oder zu einer dedizierten Not-Found-Seite, die das Problem erklärt.

Dieser Ansatz verhindert, dass ungültige Locales Ihre Komponenten und i18n-Provider erreichen. Durch die Rückgabe einer Redirect-Response aus dem Loader nutzen Sie das integrierte Navigationssystem von React Router, um den Fehler elegant zu behandeln. Die Weiterleitung erfolgt während des SSR auf dem Server oder während der Navigation auf dem Client und gewährleistet so ein konsistentes Verhalten über alle Rendering-Strategien hinweg. Benutzer erhalten unmittelbares Feedback durch die URL-Änderung, und Ihre Anwendung vermeidet den Versuch, Ressourcen für nicht existierende Locales zu laden.

Schritte

1. Definieren Sie Ihre unterstützten Locales

Erstellen Sie eine Liste gültiger Locale-Codes, die Ihre Anwendung unterstützt. Diese Liste dient als zentrale Quelle für die Validierung.

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

export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];

export function isValidLocale(locale: string): locale is SupportedLocale {
  return SUPPORTED_LOCALES.includes(locale as SupportedLocale);
}

Diese Hilfsfunktion bietet typsichere Validierung und kann in Loadern und anderen Teilen Ihrer Anwendung wiederverwendet werden.

2. Fügen Sie Validierung zu Ihrem Locale-präfixierten Route-Loader hinzu

Exportieren Sie im Route-Modul für Ihre Locale-präfixierten Seiten einen Loader, der den Locale-Parameter überprüft und bei Ungültigkeit weiterleitet.

import type { Route } from "./+types/page";
import { redirect } from "react-router";
import { isValidLocale } from "~/i18n/locales";

export async function loader({ params }: Route.LoaderArgs) {
  const { locale } = params;

  if (!locale || !isValidLocale(locale)) {
    return redirect("/en/not-found");
  }

  return { locale };
}

export default function Page({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      <h1>Content in {loaderData.locale}</h1>
    </div>
  );
}

Der Loader extrahiert das Locale aus der URL, validiert es und leitet zu einem sicheren Fallback weiter, wenn die Validierung fehlschlägt. Wenn das Locale gültig ist, gibt er Daten zurück, die Komponenten verwenden können.

3. Konfigurieren Sie Ihre Routen mit Locale-Parametern

Definieren Sie in Ihrer routes.ts-Datei Routen, die das Locale als dynamisches Segment enthalten.

import { type RouteConfig, route } from "@react-router/dev/routes";

export default [
  route(":locale/about", "./routes/about.tsx"),
  route(":locale/contact", "./routes/contact.tsx"),
  route(":locale/not-found", "./routes/not-found.tsx"),
] satisfies RouteConfig;

Jede Route mit einem :locale-Parameter ruft ihren Loader auf, wo die Validierung erfolgt, bevor die Komponente gerendert wird.

4. Erstellen Sie eine Not-Found-Seite für ungültige Locales

Erstellen Sie eine dedizierte Seite, die erklärt, dass das Locale nicht gefunden wurde, und Navigationsoptionen anbietet.

import { Link } from "react-router";
import { SUPPORTED_LOCALES } from "~/i18n/locales";

export default function NotFound() {
  return (
    <div>
      <h1>Language Not Found</h1>
      <p>The requested language is not supported.</p>
      <nav>
        <p>Choose a language:</p>
        <ul>
          {SUPPORTED_LOCALES.map((locale) => (
            <li key={locale}>
              <Link to={`/${locale}`}>{locale.toUpperCase()}</Link>
            </li>
          ))}
        </ul>
      </nav>
    </div>
  );
}

Diese Seite bietet klares Feedback und umsetzbare nächste Schritte und hilft Benutzern, sich vom Fehler zu erholen, ohne Ihre Anwendung zu verlassen.

5. Catch-all-Route für vollständig ungültige Pfade hinzufügen

Fügen Sie für URLs, die keinem definierten Routenmuster entsprechen, am Ende Ihrer Routenkonfiguration eine Splat-Route hinzu.

import { type RouteConfig, route } from "@react-router/dev/routes";

export default [
  route(":locale/about", "./routes/about.tsx"),
  route(":locale/contact", "./routes/contact.tsx"),
  route(":locale/not-found", "./routes/not-found.tsx"),
  route("*", "./routes/catch-all.tsx"),
] satisfies RouteConfig;

Die Splat-Route passt auf jeden Pfad, der nicht auf frühere Routen passt, und ermöglicht es Ihnen, vollständig fehlerhafte URLs getrennt von ungültigen Locale-Codes zu behandeln.

6. Optional auf eine Standard-Locale umleiten statt eine Not-Found-Seite anzuzeigen

Wenn Sie ungültige Locales lieber stillschweigend korrigieren möchten, anstatt einen Fehler anzuzeigen, leiten Sie auf denselben Pfad mit einer Standard-Locale um.

import type { Route } from "./+types/page";
import { redirect } from "react-router";
import { isValidLocale } from "~/i18n/locales";

const DEFAULT_LOCALE = "en";

export async function loader({ params, request }: Route.LoaderArgs) {
  const { locale } = params;

  if (!locale || !isValidLocale(locale)) {
    const url = new URL(request.url);
    const newPath = url.pathname.replace(/^\/[^/]+/, `/${DEFAULT_LOCALE}`);
    return redirect(newPath);
  }

  return { locale };
}

Dieser Ansatz bewahrt den Rest des URL-Pfads, während nur das ungültige Locale-Segment ersetzt wird, und bietet eine reibungslosere Benutzererfahrung, wenn die Locale das einzige Problem ist.