So erstellen Sie eine Sprachumschalter-Komponente in TanStack Start v1

Problem

Wenn Benutzer in einer mehrsprachigen Anwendung die Sprache wechseln, erwarten sie, auf derselben Seite zu bleiben und denselben Inhalt in der neuen Sprache anzuzeigen. Ein schlecht implementierter Sprachumschalter behandelt die Sprachauswahl als Navigation zu einem anderen Ziel und leitet Benutzer häufig zur Startseite um, wodurch sie ihre Position vollständig verlieren. Dies unterbricht den Benutzerfluss und führt zu Frustration, insbesondere wenn sich Benutzer tief in einem Workflow befinden oder bestimmte Inhalte anzeigen. Die Herausforderung besteht darin, einen Umschalter zu erstellen, der nur das Sprachsegment der URL ändert und dabei den Rest des Pfads, die Suchparameter und den Hash beibehält.

Lösung

Erstellen Sie eine Sprachumschalter-Komponente, die den aktuellen URL-Pfadnamen liest und Links für jede verfügbare Sprache erstellt, indem sie das Locale-Segment im Pfad ersetzt. Extrahieren Sie das aktuelle Locale aus der URL-Struktur und generieren Sie dann neue Pfade für andere unterstützte Sprachen, indem Sie den Locale-Teil ersetzen und dabei alle anderen URL-Segmente intakt lassen. Verwenden Sie diese Pfade, um Links zu rendern, die es Benutzern ermöglichen, die Sprache zu wechseln, ohne ihren aktuellen Seitenkontext zu verlieren.

Schritte

1. Unterstützte Locales definieren

Erstellen Sie eine Konfigurationsdatei, die alle von Ihrer Anwendung unterstützten Sprachen auflistet und das Standard-Locale identifiziert.

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

export type Locale = (typeof locales)[number];

export const defaultLocale: Locale = "en";

Diese Konfiguration dient als Single Source of Truth für verfügbare Sprachen und wird zur Generierung von Umschalter-Links verwendet.

2. Einen Helper erstellen, um das aktuelle Locale aus dem Pfadnamen zu extrahieren

Schreiben Sie eine Utility-Funktion, die den Pfadnamen parst und das Locale-Segment extrahiert, falls vorhanden.

import { defaultLocale, locales, type Locale } from "./locales";

export function getLocaleFromPathname(pathname: string): Locale {
  const segments = pathname.split("/").filter(Boolean);
  const firstSegment = segments[0];

  if (firstSegment && locales.includes(firstSegment as Locale)) {
    return firstSegment as Locale;
  }

  return defaultLocale;
}

Diese Funktion überprüft das erste Pfadsegment und gibt es zurück, wenn es mit einer unterstützten Locale übereinstimmt, andernfalls wird auf die Standardeinstellung zurückgegriffen.

3. Erstellen Sie eine Hilfsfunktion zum Erstellen lokalisierter Pfade

Schreiben Sie eine Funktion, die den aktuellen Pfadnamen und eine Ziel-Locale entgegennimmt und dann einen neuen Pfad erstellt, bei dem das Locale-Segment ersetzt wird.

import { defaultLocale, locales, type Locale } from "./locales";

export function getLocalizedPath(
  pathname: string,
  targetLocale: Locale,
): string {
  const segments = pathname.split("/").filter(Boolean);
  const firstSegment = segments[0];

  const hasLocalePrefix =
    firstSegment && locales.includes(firstSegment as Locale);

  if (hasLocalePrefix) {
    segments[0] = targetLocale;
  } else {
    segments.unshift(targetLocale);
  }

  return "/" + segments.join("/");
}

Diese Funktion ersetzt entweder ein vorhandenes Locale-Segment oder stellt die Ziel-Locale dem Pfad voran, um sicherzustellen, dass die neue URL auf dieselbe Seite in einer anderen Sprache verweist.

4. Erstellen Sie die Sprachumschaltungs-Komponente

Erstellen Sie eine Komponente, die den aktuellen Standort verwendet, um Links für alle unterstützten Sprachen zu generieren.

import { Link } from "@tanstack/react-router";
import { useLocation } from "@tanstack/react-router";
import { locales, type Locale } from "./locales";
import { getLocaleFromPathname, getLocalizedPath } from "./locale-helpers";

export function LanguageSwitcher() {
  const location = useLocation();
  const currentLocale = getLocaleFromPathname(location.pathname);

  return (
    <nav>
      <ul>
        {locales.map((locale) => {
          const isActive = locale === currentLocale;
          const localizedPath = getLocalizedPath(location.pathname, locale);

          return (
            <li key={locale}>
              <Link
                to={localizedPath}
                search={location.search}
                hash={location.hash}
                aria-current={isActive ? "page" : undefined}
              >
                {locale.toUpperCase()}
              </Link>
            </li>
          );
        })}
      </ul>
    </nav>
  );
}

Die Komponente liest den aktuellen Pfadnamen, ermittelt die aktive Locale und rendert einen Link für jede unterstützte Sprache, der die aktuelle Seitenstruktur, Suchparameter und Hash-Fragmente beibehält. Benutzer können die Sprache wechseln, während sie auf derselben logischen Seite bleiben.