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 langue sur l'élément HTML racine, les navigateurs ne peuvent pas déterminer la langue du contenu et doivent deviner. Cela amène les lecteurs d'écran à utiliser par défaut la langue système de l'utilisateur, ce qui entraîne une prononciation incorrecte lorsque la langue du contenu est différente. Les navigateurs ne peuvent pas offrir de fonctionnalités de traduction précises car ils manquent d'informations sur la langue source. Les moteurs de recherche peinent à indexer avec confiance le contenu pour le public de la langue 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 le shellComponent de la route racine, qui restitue la structure du document, y compris 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 enveloppe 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, comme 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 la 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 maintenant 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 à partir de votre système de routage ou de gestion d'état et transmettez-la au composant principal.

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 maintenant à jour en fonction de la locale active, garantissant que l'attribut lang reflète toujours la langue actuelle du contenu.