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

Problem

Wenn ein Benutzer explizit eine Sprache auswählt, stellt diese Auswahl 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 und zwingt Benutzer dazu, ihre Sprache wiederholt neu auszuwählen. Dies erzeugt Reibung und signalisiert, dass die Anwendung Benutzerentscheidungen nicht respektiert, was die Gesamterfahrung verschlechtert und möglicherweise dazu führt, dass Benutzer die Website verlassen, bevor sie ihre beabsichtigten Aufgaben abschließen.

Lösung

Speichern Sie die Sprachauswahl des Benutzers in einem persistenten Cookie, wenn eine explizite Auswahl getroffen wird. Bei nachfolgenden Besuchen wird diese gespeicherte Präferenz überprüft, bevor auf automatische Erkennungsmethoden wie Browser-Header zurückgegriffen wird. Wenn eine gültige gespeicherte Sprache gefunden wird, leiten Sie den Benutzer vom Stammverzeichnis der Website zum Pfad dieser Sprache weiter und stellen so sicher, dass er direkt in seiner bevorzugten Sprache landet, ohne zusätzliche Schritte.

Schritte

1. Erstellen einer Serverfunktion zur Speicherung der Sprachpräferenz

Serverfunktionen ermöglichen es, serverseitige Logik zu definieren, die von überall in Ihrer Anwendung aufgerufen werden kann. Definieren Sie eine Funktion, die die ausgewählte Sprache in einem Cookie speichert.

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 Serverfunktion verwendet setCookie aus @tanstack/react-start/server, um die Sprachpräferenz zu speichern und sie für zukünftige Anfragen verfügbar zu machen.

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

In Ihrer Sprachumschalter-Komponente rufen Sie die Serverfunktion 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 Locale navigiert wird.

3. Erstellen Sie eine Serverfunktion zum Lesen der gespeicherten Präferenz

Definieren Sie eine Funktion, die die gespeicherte Locale 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 Funktion getCookie aus @tanstack/react-start/server liest den Cookie-Wert, der bei früheren Besuchen gesetzt wurde.

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

Verwenden Sie die Funktion redirect 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 dieser Locale weiter, wenn sie gültig ist, andernfalls wird auf die Standardeinstellung zurückgegriffen.

5. Validieren Sie die gespeicherte Sprache gegen unterstützte Sprachen

Fügen Sie eine Validierung hinzu, um sicherzustellen, dass der gespeicherte Wert eine erkannte Sprache ist, bevor Sie weiterleiten.

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 Sprachen und schützt vor Cookie-Manipulation oder veralteten Werten.