Comment détecter les préférences linguistiques de l'utilisateur dans TanStack Start v1

Problème

Les navigateurs web envoient un en-tête Accept-Language avec chaque requête HTTP, indiquant les langues préférées de l'utilisateur par ordre de priorité. Cet en-tête fournit des informations précieuses sur la langue avec laquelle l'utilisateur est le plus à l'aise, pourtant de nombreuses applications l'ignorent complètement. Au lieu de cela, elles affichent une langue par défaut—généralement l'anglais—à tous les visiteurs, indépendamment de leurs préférences réelles. Les utilisateurs doivent alors rechercher manuellement un sélecteur de langue, créant une friction inutile alors que l'application dispose déjà des informations nécessaires pour faire un meilleur choix initial.

Cette opportunité manquée de personnalisation est particulièrement frustrante pour les locuteurs non anglophones qui ont explicitement configuré les préférences linguistiques de leur navigateur. Le résultat est une première impression dégradée et des étapes supplémentaires avant que les utilisateurs puissent interagir avec le contenu dans leur langue préférée.

Solution

Interceptez les requêtes vers le chemin racine et examinez l'en-tête Accept-Language pour déterminer la langue préférée de l'utilisateur. Analysez l'en-tête pour extraire la langue de priorité la plus élevée que votre application prend en charge. Si une correspondance est trouvée, redirigez l'utilisateur vers la route localisée appropriée. Si aucune langue prise en charge n'est trouvée dans l'en-tête, redirigez vers une langue de secours par défaut.

Cette approche respecte automatiquement les préférences de l'utilisateur tout en maintenant une structure d'URL claire où chaque langue possède son propre préfixe de chemin. La redirection se produit côté serveur avant le rendu de la page, garantissant que les utilisateurs arrivent directement sur le contenu dans leur langue préférée sans voir un flash de la mauvaise langue.

Étapes

1. Créer une fonction utilitaire pour analyser l'en-tête Accept-Language

L'en-tête Accept-Language contient des codes de langue avec des valeurs de qualité optionnelles qui indiquent l'ordre de préférence. Créez un analyseur qui extrait ces langues, les trie par priorité et trouve la première correspondance dans votre liste de langues prises en charge.

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

Cette fonction divise l'en-tête par des virgules, extrait les valeurs de qualité, trie par préférence et vérifie les correspondances exactes ainsi que les correspondances de langue de base par rapport à vos paramètres régionaux pris en charge.

2. Définissez vos paramètres régionaux pris en charge

Créez une configuration qui répertorie toutes les langues prises en charge par votre application et spécifie celle à utiliser comme solution de repli par défaut.

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

Ces constantes centralisent la configuration de vos langues et facilitent l'ajout ou la suppression de langues prises en charge au fur et à mesure que votre application évolue.

3. Créez un gestionnaire de route serveur pour le chemin racine

Ajoutez un gestionnaire GET côté serveur à votre route index qui lit l'en-tête Accept-Language, détermine les meilleurs paramètres régionaux et redirige l'utilisateur vers le chemin spécifique à la langue appropriée.

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

Ce gestionnaire s'exécute sur le serveur lorsqu'un utilisateur visite le chemin racine, examine ses préférences linguistiques et le redirige immédiatement vers la route de paramètres régionaux correspondant le mieux avant l'exécution de tout code côté client.

4. Importez la fonction d'aide

Assurez-vous que la fonction d'aide d'analyse est disponible dans votre fichier de route en l'important en haut avec votre configuration de paramètres régionaux.

import { createFileRoute, redirect } from "@tanstack/react-router";
import { getRequestHeaders } from "@tanstack/react-start/server";
import {
  parseAcceptLanguage,
  SUPPORTED_LOCALES,
  DEFAULT_LOCALE,
} from "../lib/locale";

Placez la fonction parseAcceptLanguage et les constantes de paramètres régionaux dans un module partagé afin qu'elles puissent être réutilisées dans votre application si nécessaire.