Wie man die Sprachauswahl über Sitzungen hinweg in TanStack Start v1 speichert

Problem

Wenn ein Benutzer explizit eine Sprache auswählt, stellt diese Wahl eine bewusste Präferenz dar, die über die aktuelle Browser-Sitzung hinaus bestehen bleiben sollte. Ohne Persistenz vergisst die Anwendung diese Präferenz bei jedem Besuch, wodurch Benutzer gezwungen werden, ihre Sprache wiederholt neu auszuwählen. Dies erzeugt Reibung und signalisiert, dass die Anwendung Benutzerentscheidungen nicht respektiert, was das Gesamterlebnis beeinträchtigt und möglicherweise dazu führt, dass Benutzer die Website verlassen, bevor sie ihre beabsichtigten Aufgaben abschließen.

Lösung

Speichern Sie die Sprachwahl des Benutzers in einem persistenten Cookie, wenn dieser eine explizite Auswahl trifft. Bei nachfolgenden Besuchen prüfen Sie auf diese gespeicherte Präferenz, bevor Sie auf automatische Erkennungsmethoden wie Browser-Header zurückgreifen. Wenn eine gültige gespeicherte Sprache gefunden wird, leiten Sie den Benutzer von der Website-Root zum Pfad dieser Sprache weiter, sodass dieser direkt in seinem bevorzugten Gebietsschema landet, ohne zusätzliche Schritte.

Schritte

1. Erstellen Sie eine Server-Funktion zum Speichern der Sprachpräferenz

Server-Funktionen ermöglichen es Ihnen, reine Server-Logik zu definieren, die von überall in Ihrer Anwendung aufgerufen werden kann. Definieren Sie eine Funktion, die das ausgewählte Gebietsschema in ein Cookie schreibt.

import { createServerFn } from "@tanstack/react-start";
import { setCookie } from "@tanstack/react-start/server";

const LOCALE_COOKIE = "user_locale";
const COOKIE_MAX_AGE = 60 * 60 * 24 * 365;

export const saveLocalePreference = createServerFn({ method: "POST" })
  .validator((locale: string) => locale)
  .handler(async ({ data }) => {
    setCookie(LOCALE_COOKIE, data, {
      maxAge: COOKIE_MAX_AGE,
      path: "/",
      sameSite: "lax",
    });
    return { success: true };
  });

Diese Server-Funktion verwendet setCookie aus @tanstack/react-start/server, um die Gebietsschemapräferenz zu speichern und bei zukünftigen Anfragen verfügbar zu machen.

2. Rufen Sie die Speicherfunktion auf, wenn der Benutzer eine Sprache auswählt

Rufen Sie in Ihrer Sprachumschalter-Komponente die Server-Funktion auf, nachdem der Benutzer eine Auswahl getroffen hat.

import { useNavigate } from "@tanstack/react-router";
import { saveLocalePreference } from "./locale-preference";

export function LanguageSwitcher({ currentLocale }: { currentLocale: string }) {
  const navigate = useNavigate();

  const handleLocaleChange = async (newLocale: string) => {
    await saveLocalePreference({ data: newLocale });
    navigate({ to: `/${newLocale}` });
  };

  return (
    <select
      value={currentLocale}
      onChange={(e) => handleLocaleChange(e.target.value)}
    >
      <option value="en">English</option>
      <option value="es">Español</option>
      <option value="fr">Français</option>
    </select>
  );
}

Dies stellt sicher, dass die Präferenz gespeichert wird, bevor zur neuen Sprache navigiert wird.

3. Erstellen Sie eine Server-Funktion zum Lesen der gespeicherten Präferenz

Definieren Sie eine Funktion, die das gespeicherte Gebietsschema aus dem Cookie abruft.

import { createServerFn } from "@tanstack/react-start";
import { getCookie } from "@tanstack/react-start/server";

const LOCALE_COOKIE = "user_locale";

export const getStoredLocale = createServerFn({ method: "GET" }).handler(
  async () => {
    const stored = getCookie(LOCALE_COOKIE);
    return stored || null;
  },
);

Die getCookie-Funktion aus @tanstack/react-start/server liest den Cookie-Wert, der bei vorherigen Besuchen gesetzt wurde.

4. Prüfen Sie auf gespeicherte Präferenz auf der Root-Route

Verwenden Sie die redirect-Funktion im beforeLoad-Callback einer Route, um eine Weiterleitung auszulösen, wenn eine gespeicherte Präferenz gefunden wird.

import { createFileRoute, redirect } from "@tanstack/react-router";
import { getStoredLocale } from "./locale-preference";

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

export const Route = createFileRoute("/")({
  beforeLoad: async () => {
    const stored = await getStoredLocale();

    if (stored && SUPPORTED_LOCALES.includes(stored)) {
      throw redirect({ to: `/${stored}` });
    }

    throw redirect({ to: `/${DEFAULT_LOCALE}` });
  },
});

Dies prüft zuerst die gespeicherte Präferenz und leitet zu diesem Gebietsschema weiter, falls gültig, andernfalls wird auf die Standardeinstellung zurückgegriffen.

5. Validieren Sie das gespeicherte Gebietsschema gegen unterstützte Sprachen

Fügen Sie eine Validierung hinzu, um sicherzustellen, dass der gespeicherte Wert ein erkanntes Gebietsschema ist, bevor weitergeleitet wird.

import { createFileRoute, redirect } from "@tanstack/react-router";
import { getStoredLocale } from "./locale-preference";

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

function isValidLocale(value: string | null): value is string {
  return value !== null && SUPPORTED_LOCALES.includes(value as any);
}

export const Route = createFileRoute("/")({
  beforeLoad: async () => {
    const stored = await getStoredLocale();
    const locale = isValidLocale(stored) ? stored : "en";
    throw redirect({ to: `/${locale}` });
  },
});

Dies verhindert Weiterleitungen zu ungültigen oder nicht unterstützten Gebietsschemata und schützt vor Cookie-Manipulation oder veralteten Werten.