Implementierung von Locale-basiertem Routing in TanStack Start v1

Problem

Beim Erstellen einer mehrsprachigen Anwendung bestimmt eine grundlegende Entscheidung alles andere: Wie erfährt die Anwendung, 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 bestimmten Sprachversionen teilen, und Suchmaschinen haben Schwierigkeiten zu verstehen, welche Version zu welcher Zielgruppe gehört. Diese Mehrdeutigkeit führt zu Problemen sowohl bei der Benutzererfahrung als auch bei der SEO, da es keine klare Möglichkeit gibt, zwischen Sprachvarianten desselben Inhalts zu unterscheiden.

Lösung

Fügen Sie eine Sprachkennung direkt in den URL-Pfad ein, z. B. /en/about oder /fr/about. Dadurch wird jeder Pfad eindeutig einer bestimmten Sprache zugeordnet, wodurch die Mehrdeutigkeit sowohl für Benutzer als auch für Suchmaschinen beseitigt wird. Durch die Verwendung eines Locale-Parameters in der Route-Struktur wird jede URL selbstbeschreibend und teilbar, sodass Benutzer Links zu Inhalten in ihrer bevorzugten Sprache mit einem Lesezeichen versehen oder teilen können, während Suchmaschinen jede Sprachvariante ordnungsgemäß indexieren können.

Schritte

1. Locale-Layout-Route erstellen

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

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

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

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

Diese Route passt sowohl auf /about (Locale ist undefined) als auch auf /en/about (Locale ist "en"), sodass Sie URLs mit oder ohne Locale-Präfix unterstützen können.

2. Erstellen Sie untergeordnete Routen unter dem Locale-Layout

TanStack Router verwendet verschachtelte Routen, um die URL mit dem korrekten zu rendernden Komponentenbaum 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 mit Zugriff auf den Locale-Parameter rendern.

3. Greifen Sie auf den Locale-Parameter in Komponenten zu

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, sodass die Anwendung sowohl lokalisierte als auch nicht lokalisierte URLs verarbeiten kann.

4. Erstellen Sie Links, 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>
  );
}

Durch Übergabe der aktuellen Locale in der params-Prop generieren Links automatisch URLs, die dem aktuellen Sprachkontext des Benutzers entsprechen, wie z. B. /fr/about beim Anzeigen der französischen Version.