Comment mémoriser la sélection de langue entre les sessions dans TanStack Start v1

Problème

Lorsqu'un utilisateur sélectionne explicitement une langue, ce choix représente une préférence délibérée qui devrait persister au-delà de la session de navigation actuelle. Sans persistance, l'application oublie cette préférence à chaque visite, obligeant les utilisateurs à resélectionner leur langue de manière répétée. Cela crée des frictions et signale que l'application ne respecte pas les choix des utilisateurs, dégradant l'expérience globale et pouvant potentiellement amener les utilisateurs à abandonner le site avant d'accomplir leurs tâches prévues.

Solution

Stocker le choix de langue de l'utilisateur dans un cookie persistant lorsqu'il effectue une sélection explicite. Lors des visites suivantes, vérifier cette préférence stockée avant de recourir aux méthodes de détection automatique comme les en-têtes du navigateur. Si une langue stockée valide est trouvée, rediriger l'utilisateur depuis la racine du site vers le chemin de cette langue, en s'assurant qu'il arrive directement dans sa locale préférée sans étapes supplémentaires.

Étapes

1. Créer une fonction serveur pour stocker la préférence de langue

Les fonctions serveur vous permettent de définir une logique côté serveur uniquement qui peut être appelée depuis n'importe où dans votre application. Définissez une fonction qui écrit la locale sélectionnée dans un cookie.

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 };
  });

Cette fonction serveur utilise setCookie depuis @tanstack/react-start/server pour stocker la préférence de locale, la rendant disponible lors des requêtes futures.

2. Appeler la fonction de sauvegarde lorsque l'utilisateur sélectionne une langue

Dans votre composant de sélection de langue, invoquez la fonction serveur après que l'utilisateur ait effectué une sélection.

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>
  );
}

Cela garantit que la préférence est sauvegardée avant de naviguer vers la nouvelle locale.

3. Créer une fonction serveur pour lire la préférence stockée

Définissez une fonction qui récupère la locale stockée depuis le cookie.

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;
  },
);

La fonction getCookie de @tanstack/react-start/server lit la valeur du cookie définie lors des visites précédentes.

4. Vérifier la préférence stockée sur la route racine

Utilisez la fonction redirect dans le callback beforeLoad d'une route pour déclencher une redirection lorsqu'une préférence stockée est trouvée.

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}` });
  },
});

Cela vérifie d'abord la préférence stockée et redirige vers cette locale si elle est valide, sinon revient à la locale par défaut.

5. Valider la locale stockée par rapport aux langues prises en charge

Ajoutez une validation pour vous assurer que la valeur stockée est une locale reconnue avant de rediriger.

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}` });
  },
});

Cela empêche les redirections vers des locales invalides ou non prises en charge, protégeant contre la manipulation des cookies ou les valeurs obsolètes.