So erkennen Sie Sprachpräferenzen der Benutzer in TanStack Start v1

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 vertraut ist, dennoch ignorieren viele Anwendungen ihn vollständig. Stattdessen zeigen sie allen Besuchern eine Standardsprache – typischerweise Englisch – unabhängig von deren tatsächlichen Präferenzen. Benutzer müssen dann manuell nach einem Sprachumschalter suchen, was unnötige Reibung erzeugt, obwohl die Anwendung bereits über die Informationen verfügt, die für eine bessere initiale Auswahl erforderlich sind.

Diese verpasste Gelegenheit zur Personalisierung ist besonders frustrierend für nicht-englischsprachige Personen, die ihre Browser-Sprachpräferenzen 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

Fangen Sie Anfragen an den Root-Pfad ab und untersuchen Sie den Accept-Language-Header, um die bevorzugte Sprache des Benutzers zu ermitteln. Parsen Sie den Header, um die Sprache mit der höchsten Priorität zu extrahieren, die Ihre Anwendung unterstützt. Wenn eine Übereinstimmung gefunden wird, leiten Sie den Benutzer zur entsprechenden lokalisierten Route weiter. Wenn keine unterstützte Sprache im Header gefunden wird, leiten Sie zu einer Standard-Sprachfallback-Option weiter.

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

Schritte

1. Erstellen Sie eine Hilfsfunktion zum Parsen des Accept-Language-Headers

Der Accept-Language-Header enthält Sprachcodes mit optionalen Qualitätswerten, die die Präferenzreihenfolge angeben. Erstellen Sie einen Parser, der diese Sprachen extrahiert, nach Priorität sortiert und die erste Übereinstimmung aus Ihrer Liste unterstützter 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 durch Kommas, extrahiert Qualitätswerte, sortiert nach Präferenz und prüft sowohl auf exakte Übereinstimmungen als auch auf Basissprachen-Übereinstimmungen mit Ihren unterstützten Locales.

2. Definieren Sie Ihre unterstützten Locales

Erstellen Sie eine Konfiguration, die alle von Ihrer Anwendung unterstützten Sprachen auflistet und festlegt, 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, während 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 Locale ermittelt 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, untersucht dessen Sprachpräferenzen und leitet ihn sofort zur am besten passenden Locale-Route weiter, bevor clientseitiger Code ausgeführt wird.

4. Importieren Sie die Hilfsfunktion

Stellen Sie sicher, dass der Parse-Helper in Ihrer Route-Datei verfügbar ist, indem Sie ihn oben zusammen mit Ihrer Locale-Konfiguration 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 Locale-Konstanten in einem gemeinsam genutzten Modul, damit sie bei Bedarf in Ihrer gesamten Anwendung wiederverwendet werden können.