Comment définir la langue du document dans TanStack Start v1

Déclarer la langue de la page pour les navigateurs et les lecteurs d'écran

Problème

Les pages web doivent déclarer leur langue principale pour fonctionner correctement sur différents agents utilisateurs. Sans déclaration explicite de la langue sur l'élément HTML racine, les navigateurs ne peuvent pas déterminer la langue du contenu et doivent deviner. Cela entraîne le basculement des lecteurs d'écran vers la langue système de l'utilisateur, ce qui provoque une prononciation incorrecte lorsque la langue du contenu diffère. Les navigateurs ne peuvent pas proposer de fonctionnalités de traduction précises car ils manquent d'informations sur la langue source. Les moteurs de recherche ont du mal à indexer le contenu avec confiance pour l'audience linguistique appropriée, réduisant ainsi la découvrabilité pour les utilisateurs effectuant des recherches dans cette langue.

Solution

Ajoutez un attribut lang à la balise html pour définir la langue par défaut de votre page. Dans TanStack Start, la structure HTML est définie dans la propriété shellComponent de la route racine, qui génère la structure du document incluant l'élément <html>. En ajoutant l'attribut lang avec le code de langue approprié à cet élément, vous informez les navigateurs, les technologies d'assistance et les moteurs de recherche de la langue du contenu, leur permettant de le traiter et de le présenter correctement.

Étapes

1. Identifier la locale actuelle

La propriété shellComponent de la route racine définit la structure HTML qui englobe tout le contenu des routes et est toujours rendue côté serveur. Déterminez la locale actuelle à partir du mécanisme de détection de locale de votre application, tel que les paramètres de route, les cookies ou les en-têtes.

import type { ReactNode } from "react";
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";

export const Route = createRootRoute({
  shellComponent: RootDocument,
  component: RootComponent,
});

function RootComponent() {
  return <Outlet />;
}

function RootDocument({ children }: { children: ReactNode }) {
  const locale = "en";

  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

Cela établit la structure de base où vous ajouterez l'attribut de langue.

2. Ajouter l'attribut lang à l'élément html

Définissez l'attribut lang sur l'élément <html> en utilisant la valeur de locale. Utilisez une balise de langue BCP 47 valide qui correspond à la langue de votre contenu.

function RootDocument({ children }: { children: ReactNode }) {
  const locale = "en";

  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

L'attribut lang déclare désormais la langue du document, permettant aux navigateurs et aux technologies d'assistance de traiter le contenu de manière appropriée.

3. Utiliser des valeurs de locale dynamiques

Si votre application prend en charge plusieurs locales, récupérez la locale actuelle depuis votre système de routage ou de gestion d'état et transmettez-la au composant shell.

function RootDocument({ children }: { children: ReactNode }) {
  const locale = getCurrentLocale();

  return (
    <html lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

function getCurrentLocale(): string {
  return "en";
}

La langue du document se met désormais à jour en fonction de la locale active, garantissant que l'attribut lang reflète toujours la langue actuelle du contenu.