Cómo recordar la selección de idioma entre sesiones en TanStack Start v1

Problema

Cuando un usuario selecciona explícitamente un idioma, esa elección representa una preferencia deliberada que debería persistir más allá de la sesión actual del navegador. Sin persistencia, la aplicación olvida esta preferencia en cada visita, obligando a los usuarios a reseleccionar su idioma repetidamente. Esto crea fricción y señala que la aplicación no respeta las elecciones del usuario, degradando la experiencia general y potencialmente causando que los usuarios abandonen el sitio antes de completar sus tareas previstas.

Solución

Almacenar la elección de idioma del usuario en una cookie persistente cuando realiza una selección explícita. En visitas posteriores, verificar esta preferencia almacenada antes de recurrir a métodos de detección automática como los encabezados del navegador. Si se encuentra un idioma almacenado válido, redirigir al usuario desde la raíz del sitio a la ruta de ese idioma, asegurando que llegue directamente a su configuración regional preferida sin pasos adicionales.

Pasos

1. Crear una función de servidor para almacenar la preferencia de idioma

Las funciones de servidor te permiten definir lógica exclusiva del servidor que puede ser llamada desde cualquier lugar de tu aplicación. Define una función que escriba la configuración regional seleccionada en una 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 };
  });

Esta función de servidor utiliza setCookie de @tanstack/react-start/server para almacenar la preferencia de configuración regional, haciéndola disponible en futuras solicitudes.

2. Llamar a la función de guardado cuando el usuario selecciona un idioma

En tu componente selector de idioma, invoca la función de servidor después de que el usuario realice una selección.

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

Esto asegura que la preferencia se guarde antes de navegar a la nueva configuración regional.

3. Crear una función de servidor para leer la preferencia almacenada

Define una función que recupere la configuración regional almacenada en la 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 función getCookie de @tanstack/react-start/server lee el valor de la cookie establecido en visitas anteriores.

4. Verifica la preferencia almacenada en la ruta raíz

Usa la función redirect en el callback beforeLoad de una ruta para activar una redirección cuando se encuentre una preferencia almacenada.

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

Esto verifica primero la preferencia almacenada y redirige a esa configuración regional si es válida; de lo contrario, recurre a la predeterminada.

5. Valida la configuración regional almacenada contra los idiomas admitidos

Agrega validación para asegurarte de que el valor almacenado sea una configuración regional reconocida antes de redirigir.

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

Esto previene redirecciones a configuraciones regionales no válidas o no admitidas, protegiendo contra manipulación de cookies o valores obsoletos.