Cómo establecer el idioma del documento en React Router v7

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

Problema

Las páginas web necesitan declarar su idioma principal a los navegadores y tecnologías de asistencia. Sin una declaración explícita del idioma, los lectores de pantalla utilizan por defecto el idioma del sistema del usuario, lo que puede producir una pronunciación incorrecta cuando el idioma del contenido es diferente. Los navegadores no pueden ofrecer funciones de traducción precisas porque deben adivinar el idioma de origen. Los motores de búsqueda tienen dificultades para indexar con confianza las páginas para la audiencia del idioma correcto, reduciendo la visibilidad para los usuarios que buscan en ese idioma.

Solución

Establece el atributo lang en el elemento raíz <html> para declarar el idioma principal del documento. Este atributo acepta un código de idioma válido que indica a los navegadores, lectores de pantalla y motores de búsqueda qué idioma utiliza el contenido. Cuando el idioma se declara explícitamente, las tecnologías de asistencia pueden aplicar reglas de pronunciación correctas, los navegadores pueden ofrecer opciones de traducción apropiadas y los motores de búsqueda pueden indexar la página para la audiencia del idioma correcto.

Pasos

1. Determinar la configuración regional actual

La ruta raíz en app/root.tsx es responsable de renderizar el documento HTML raíz. Si tu aplicación utiliza enrutamiento basado en configuraciones regionales (como patrones /:locale/...), extrae la configuración regional de los parámetros de ruta. De lo contrario, utiliza una configuración regional predeterminada.

import { useParams } from "react-router";

export default function Root() {
  const params = useParams();
  const locale = params.locale || "en";

  return (
    <html lang={locale}>
      <head>
        <meta charSet="utf-8" />
      </head>
      <body>
        <h1>Content</h1>
      </body>
    </html>
  );
}

Esto lee la configuración regional de la URL si está presente y recurre al inglés cuando no existe un parámetro de configuración regional.

2. Mapear códigos de configuración regional a etiquetas de idioma

Si tu aplicación utiliza identificadores de configuración regional personalizados que difieren de las etiquetas de idioma estándar, crea una función de mapeo para convertirlos en códigos de idioma BCP 47 válidos.

function getLanguageTag(locale: string): string {
  const languageMap: Record<string, string> = {
    en: "en",
    "en-US": "en-US",
    es: "es",
    fr: "fr",
    de: "de",
    ja: "ja",
    "zh-CN": "zh-Hans",
    "zh-TW": "zh-Hant",
  };

  return languageMap[locale] || "en";
}

Esto asegura que el atributo lang reciba una etiqueta de idioma válida incluso cuando tu enrutamiento utiliza códigos de configuración regional simplificados.

3. Aplica la etiqueta de idioma al elemento HTML

Utiliza la etiqueta de idioma mapeada como valor para el atributo lang en el elemento <html> en tu componente raíz.

import { useParams } from "react-router";

function getLanguageTag(locale: string): string {
  const languageMap: Record<string, string> = {
    en: "en",
    es: "es",
    fr: "fr",
    de: "de",
  };
  return languageMap[locale] || "en";
}

export default function Root() {
  const params = useParams();
  const locale = params.locale || "en";
  const lang = getLanguageTag(locale);

  return (
    <html lang={lang}>
      <head>
        <meta charSet="utf-8" />
      </head>
      <body>
        <h1>Content</h1>
      </body>
    </html>
  );
}

El atributo lang ahora refleja el idioma actual, actualizándose automáticamente cuando los usuarios navegan entre rutas específicas de cada idioma.