Cómo establecer el idioma del documento en TanStack Start v1

Declarar el idioma de la página para navegadores y lectores de pantalla

Problema

Las páginas web deben declarar su idioma principal para funcionar correctamente en diferentes agentes de usuario. Sin una declaración explícita del idioma en el elemento HTML raíz, los navegadores no pueden determinar el idioma del contenido y deben adivinarlo. Esto hace que los lectores de pantalla utilicen por defecto el idioma del sistema del usuario, lo que resulta en una pronunciación incorrecta cuando el idioma del contenido es diferente. Los navegadores no pueden ofrecer funciones de traducción precisas porque carecen de información sobre el idioma de origen. Los motores de búsqueda tienen dificultades para indexar con confianza el contenido para la audiencia del idioma apropiado, reduciendo la capacidad de descubrimiento para los usuarios que buscan en ese idioma.

Solución

Añade un atributo lang a la etiqueta html para establecer el idioma predeterminado de tu página. En TanStack Start, el shell HTML se define en el shellComponent de la ruta raíz, que renderiza la estructura del documento incluyendo el elemento <html>. Al añadir el atributo lang con el código de idioma apropiado a este elemento, informas a los navegadores, tecnologías de asistencia y motores de búsqueda sobre el idioma del contenido, permitiéndoles procesarlo y presentarlo correctamente.

Pasos

1. Identificar el locale actual

La propiedad shellComponent de la ruta raíz define el shell HTML que envuelve todo el contenido de la ruta y siempre se renderiza en el servidor. Determina el locale actual desde el mecanismo de detección de locale de tu aplicación, como parámetros de ruta, cookies o cabeceras.

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

Esto establece la estructura del shell donde añadirás el atributo de idioma.

2. Añadir el atributo lang al elemento html

Establece el atributo lang en el elemento <html> utilizando el valor de la configuración regional. Usa una etiqueta de idioma BCP 47 válida que coincida con el idioma de tu contenido.

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

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

El atributo lang ahora declara el idioma del documento, permitiendo a los navegadores y tecnologías de asistencia manejar el contenido apropiadamente.

3. Usar valores de configuración regional dinámicos

Si tu aplicación admite múltiples configuraciones regionales, obtén la configuración regional actual desde tu sistema de enrutamiento o gestión de estado y pásala al componente 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";
}

El idioma del documento ahora se actualiza según la configuración regional activa, asegurando que el atributo lang siempre refleje el idioma actual del contenido.