Wie man lokalisierungsbasiertes Routing in TanStack Start v1 implementiert

Problem

Beim Aufbau einer mehrsprachigen Anwendung prägt eine grundlegende Entscheidung alles andere: Wie soll die Anwendung wissen, welche Sprache angezeigt werden soll? Ohne einen expliziten Mechanismus wird die URL /about mehrdeutig – sie könnte Inhalte in jeder Sprache darstellen. Benutzer können keine Links zu spezifischen Sprachversionen teilen, und Suchmaschinen haben Schwierigkeiten zu verstehen, welche Version zu welchem Publikum gehört. Diese Mehrdeutigkeit schafft Probleme sowohl für die Benutzererfahrung als auch für die Suchmaschinenoptimierung, da es keine klare Möglichkeit gibt, zwischen Sprachvarianten desselben Inhalts zu unterscheiden.

Lösung

Platziere einen Sprachidentifikator direkt im URL-Pfad, wie z.B. /en/about oder /fr/about. Dies macht jeden Pfad eindeutig für eine bestimmte Sprache und beseitigt die Mehrdeutigkeit sowohl für Benutzer als auch für Suchmaschinen. Durch die Verwendung eines Locale-Parameters in der Routenstruktur wird jede URL selbstbeschreibend und teilbar, sodass Benutzer Lesezeichen setzen oder Links zu Inhalten in ihrer bevorzugten Sprache teilen können, während Suchmaschinen jede Sprachvariante ordnungsgemäß indexieren können.

Schritte

1. Erstelle eine Locale-Layout-Route

Definiere einen optionalen Locale-Parameter mit der Syntax {-$locale}, um flexible Routing-Muster zu erstellen, bei denen der Locale-Parameter optional ist. TanStack Start verwendet dateibasiertes Routing, bei dem Routen im Verzeichnis src/routes definiert werden.

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

export const Route = createFileRoute("/{-$locale}")({
  component: LocaleLayout,
});

function LocaleLayout() {
  return <Outlet />;
}

Diese Route passt sowohl zu /about (Locale ist undefiniert) als auch zu /en/about (Locale ist "en"), sodass URLs mit oder ohne Locale-Präfix unterstützt werden können.

2. Erstelle untergeordnete Routen unter dem Locale-Layout

TanStack Router verwendet verschachteltes Routing, um die URL mit dem korrekten Komponentenbaum zum Rendern abzugleichen. Erstellen Sie Routendateien als untergeordnete Elemente des Locale-Parameters, um die Locale aus der URL zu übernehmen.

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

export const Route = createFileRoute("/{-$locale}/about")({
  component: AboutPage,
});

function AboutPage() {
  const { locale } = Route.useParams();
  const currentLocale = locale || "en";

  return (
    <div>
      <h1>About Us</h1>
      <p>Current locale: {currentLocale}</p>
    </div>
  );
}

Die Routendateistruktur {-$locale}/about.tsx erstellt Pfade wie /about und /en/about, die beide dieselbe Komponente rendern und Zugriff auf den Locale-Parameter bieten.

3. Zugriff auf den Locale-Parameter in Komponenten

Verwenden Sie den useParams-Hook, um die Locale aus der URL zu lesen und zu bestimmen, welche Sprache angezeigt werden soll.

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

export const Route = createFileRoute("/{-$locale}/products")({
  component: ProductsPage,
});

function ProductsPage() {
  const { locale } = Route.useParams();
  const displayLocale = locale || "en";

  return (
    <div>
      <h1>{displayLocale === "fr" ? "Produits" : "Products"}</h1>
    </div>
  );
}

Wenn der Locale-Parameter nicht definiert ist, verwendet die Komponente standardmäßig eine Basissprache, wodurch die Anwendung sowohl lokalisierte als auch nicht-lokalisierte URLs verarbeiten kann.

4. Links erstellen, die die Locale beibehalten

Verwenden Sie die Link-Komponente mit dem Locale-Parameter, um zwischen Seiten zu navigieren und dabei die aktuelle Sprache beizubehalten.

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

export const Route = createFileRoute("/{-$locale}/")({
  component: HomePage,
});

function HomePage() {
  const { locale } = Route.useParams();

  return (
    <nav>
      <Link to="/{-$locale}/about" params={{ locale }}>
        About
      </Link>
      <Link to="/{-$locale}/products" params={{ locale }}>
        Products
      </Link>
    </nav>
  );
}

Indem Sie die aktuelle Locale im params-Prop übergeben, generieren Links automatisch URLs, die dem aktuellen Sprachkontext des Benutzers entsprechen, wie z.B. /fr/about beim Betrachten der französischen Version.