Wie man eine Sprachumschalter-Komponente in TanStack Start v1 erstellt

Problem

Wenn Benutzer in einer mehrsprachigen Anwendung die Sprache wechseln, erwarten sie, auf derselben Seite zu bleiben und denselben Inhalt in der neuen Sprache zu sehen. Ein schlecht implementierter Sprachumschalter behandelt die Sprachauswahl als Navigation zu einem anderen Ziel, leitet Benutzer oft zur Startseite um und lässt sie ihren Platz vollständig verlieren. Dies unterbricht den Benutzerfluss und erzeugt Frustration, besonders wenn Benutzer sich in einem komplexen Arbeitsablauf befinden oder spezifische Inhalte betrachten. Die Herausforderung besteht darin, einen Umschalter zu entwickeln, der nur das Sprachsegment der URL ändert, während der Rest des Pfades, die Suchparameter und der Hash erhalten bleiben.

Lösung

Entwickle eine Sprachumschalter-Komponente, die den aktuellen URL-Pfadnamen liest und Links für jede verfügbare Sprache erstellt, indem das Locale-Segment im Pfad ersetzt wird. Extrahiere die aktuelle Locale aus der URL-Struktur und generiere dann neue Pfade für andere unterstützte Sprachen, indem du den Locale-Teil ersetzt, während alle anderen URL-Segmente intakt bleiben. Verwende 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

Erstelle eine Konfigurationsdatei, die alle Sprachen auflistet, die deine Anwendung unterstützt, und die 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 einzige Quelle der Wahrheit für verfügbare Sprachen und wird verwendet, um Umschalter-Links zu generieren.

2. Einen Helfer erstellen, um die aktuelle Locale aus dem Pfadnamen zu extrahieren

Schreibe eine Hilfsfunktion, die den Pfadnamen analysiert 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 untersucht das erste Pfadsegment und gibt es zurück, wenn es mit einer unterstützten Locale übereinstimmt, andernfalls wird auf die Standardlocale zurückgegriffen.

3. Erstelle einen Helper zum Aufbau lokalisierter Pfade

Schreibe eine Funktion, die den aktuellen Pfadnamen und eine Ziellocale nimmt und dann einen neuen Pfad konstruiert, 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 Ziellocale dem Pfad voran, wodurch sichergestellt wird, dass die neue URL auf dieselbe Seite in einer anderen Sprache verweist.

4. Erstelle die Sprachumschalter-Komponente

Erstelle 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, bestimmt 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.