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

Declara 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 difiere. 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 el contenido con confianza 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, la estructura 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. Identifica la configuración regional actual

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

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 base donde añadirás el atributo de idioma.

2. Añade el atributo lang al elemento html

Establece el atributo lang en el elemento <html> usando el valor de la configuración regional. Utiliza 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 que los navegadores y las tecnologías de asistencia gestionen el contenido de manera apropiada.

3. Usa 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 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";
}

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