Wie man Sprachpräferenzen der Benutzer in TanStack Start v1 erkennt

Problem

Webbrowser senden mit jeder HTTP-Anfrage einen Accept-Language-Header, der die bevorzugten Sprachen des Benutzers in der Reihenfolge ihrer Priorität angibt. Dieser Header liefert wertvolle Informationen darüber, mit welcher Sprache der Benutzer am besten zurechtkommt, dennoch ignorieren viele Anwendungen ihn vollständig. Stattdessen zeigen sie allen Besuchern eine Standardsprache – typischerweise Englisch – unabhängig von deren tatsächlichen Präferenzen an. Benutzer müssen dann manuell nach einem Sprachumschalter suchen, was unnötige Reibung verursacht, obwohl die Anwendung bereits über die Informationen verfügt, die für eine bessere Erstauswahl erforderlich sind.

Diese verpasste Gelegenheit zur Personalisierung ist besonders frustrierend für Nicht-Englisch-Sprecher, die die Spracheinstellungen ihres Browsers explizit konfiguriert haben. Das Ergebnis ist ein verschlechterter erster Eindruck und zusätzliche Schritte, bevor Benutzer mit Inhalten in ihrer bevorzugten Sprache interagieren können.

Lösung

Fange Anfragen an den Root-Pfad ab und untersuche den Accept-Language-Header, um die bevorzugte Sprache des Benutzers zu ermitteln. Analysiere den Header, um die Sprache mit der höchsten Priorität zu extrahieren, die deine Anwendung unterstützt. Wenn eine Übereinstimmung gefunden wird, leite den Benutzer zur entsprechenden lokalisierten Route weiter. Wenn keine unterstützte Sprache im Header gefunden wird, leite zu einer Standard-Sprache als Fallback weiter.

Dieser Ansatz respektiert Benutzerpräferenzen automatisch und behält gleichzeitig eine klare URL-Struktur bei, bei der jede Sprache ihr eigenes Pfadpräfix hat. Die Weiterleitung erfolgt serverseitig, bevor die Seite gerendert wird, wodurch sichergestellt wird, dass Benutzer direkt auf Inhalte in ihrer bevorzugten Sprache gelangen, ohne ein Aufblitzen der falschen Sprache zu sehen.

Schritte

1. Erstelle einen Helper zum Parsen des Accept-Language-Headers

Der Accept-Language-Header enthält Sprachcodes mit optionalen Qualitätswerten, die die Präferenzreihenfolge angeben. Erstelle einen Parser, der diese Sprachen extrahiert, nach Priorität sortiert und die erste Übereinstimmung aus deiner Liste der unterstützten Sprachen findet.

export function parseAcceptLanguage(
  header: string | null,
  supportedLocales: string[],
): string | null {
  if (!header) {
    return null;
  }

  const languages = header
    .split(",")
    .map((lang) => {
      const [code, qValue] = lang.trim().split(";q=");
      const quality = qValue ? parseFloat(qValue) : 1.0;
      return { code: code.toLowerCase(), quality };
    })
    .sort((a, b) => b.quality - a.quality);

  for (const { code } of languages) {
    const exactMatch = supportedLocales.find(
      (locale) => locale.toLowerCase() === code,
    );
    if (exactMatch) {
      return exactMatch;
    }

    const baseCode = code.split("-")[0];
    const baseMatch = supportedLocales.find((locale) =>
      locale.toLowerCase().startsWith(baseCode),
    );
    if (baseMatch) {
      return baseMatch;
    }
  }

  return null;
}

Diese Funktion teilt den Header nach Kommas, extrahiert Qualitätswerte, sortiert nach Präferenz und prüft sowohl auf exakte Übereinstimmungen als auch auf Basissprachenübereinstimmungen mit deinen unterstützten Locales.

2. Definieren Sie Ihre unterstützten Sprachen

Erstellen Sie eine Konfiguration, die alle Sprachen auflistet, die Ihre Anwendung unterstützt, und legen Sie fest, welche als Standard-Fallback verwendet werden soll.

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

Diese Konstanten zentralisieren Ihre Sprachkonfiguration und erleichtern das Hinzufügen oder Entfernen unterstützter Sprachen, wenn Ihre Anwendung wächst.

3. Erstellen Sie einen Server-Route-Handler für den Root-Pfad

Fügen Sie einen serverseitigen GET-Handler zu Ihrer Index-Route hinzu, der den Accept-Language-Header liest, die beste Sprache bestimmt und den Benutzer zum entsprechenden sprachspezifischen Pfad weiterleitet.

import { createFileRoute, redirect } from "@tanstack/react-router";
import { getRequestHeaders } from "@tanstack/react-start/server";

export const Route = createFileRoute("/")({
  server: {
    handlers: {
      GET: async () => {
        const headers = getRequestHeaders();
        const acceptLanguage = headers.get("accept-language");

        const preferredLocale = parseAcceptLanguage(
          acceptLanguage,
          SUPPORTED_LOCALES,
        );

        const targetLocale = preferredLocale || DEFAULT_LOCALE;

        throw redirect({
          to: `/${targetLocale}`,
          statusCode: 302,
        });
      },
    },
  },
});

Dieser Handler wird auf dem Server ausgeführt, wenn ein Benutzer den Root-Pfad besucht, prüft dessen Spracheinstellungen und leitet ihn sofort zur am besten passenden Sprachroute weiter, bevor clientseitiger Code ausgeführt wird.

4. Importieren Sie die Hilfsfunktion

Stellen Sie sicher, dass die Parse-Hilfsfunktion in Ihrer Route-Datei verfügbar ist, indem Sie sie zusammen mit Ihrer Sprachkonfiguration oben importieren.

import { createFileRoute, redirect } from "@tanstack/react-router";
import { getRequestHeaders } from "@tanstack/react-start/server";
import {
  parseAcceptLanguage,
  SUPPORTED_LOCALES,
  DEFAULT_LOCALE,
} from "../lib/locale";

Platzieren Sie die parseAcceptLanguage-Funktion und die Sprachkonstanten in einem gemeinsam genutzten Modul, damit sie bei Bedarf in Ihrer gesamten Anwendung wiederverwendet werden können.