Cómo establecer el idioma del documento en Next.js (Pages Router) v16

Declarar 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, motores de búsqueda y tecnologías de asistencia. Sin una declaración explícita del idioma, estas herramientas deben adivinar el idioma del contenido. Los lectores de pantalla utilizan por defecto el idioma del sistema del usuario, lo que causa una pronunciación incorrecta cuando el idioma del contenido es diferente. Los navegadores no pueden ofrecer con confianza funciones de traducción porque carecen de información sobre el idioma de origen. Los motores de búsqueda tienen dificultades para indexar 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 de la página. En Next.js Pages Router, esto se hace creando un componente Document personalizado que envuelve la estructura HTML de tu aplicación. El atributo lang acepta un código de idioma estándar que indica a los navegadores, tecnologías de asistencia y motores de búsqueda qué idioma utiliza el contenido, permitiendo una pronunciación correcta, ofertas de traducción apropiadas y una indexación precisa.

Pasos

1. Crear un archivo de documento personalizado

Crea un archivo llamado _document.js (o _document.tsx para TypeScript) en tu directorio pages. Este archivo te permite personalizar la estructura del documento HTML que envuelve cada página de tu aplicación.

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

El componente Html de next/document acepta una prop lang que establece el atributo de idioma en el elemento HTML raíz. Reemplaza "en" con el código de idioma de tu contenido.

2. Usar el código de idioma apropiado

Los códigos de idioma siguen el formato estándar de Identificadores de Localización UTS: idioma-región-script, donde región y script son opcionales. Para la mayoría de los casos, usa el código de idioma ISO 639-1 de dos letras.

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="fr">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Ejemplos comunes incluyen "en" para inglés, "es" para español, "fr" para francés, "de" para alemán y "ja" para japonés. Puedes incluir variantes regionales como "en-US" o "en-GB" cuando sea necesario.

3. Establecer idioma dinámico basado en la configuración regional

Si tu aplicación admite múltiples configuraciones regionales a través del enrutamiento i18n de Next.js, accede a la configuración regional actual desde el contexto del router para establecer el idioma dinámicamente.

import Document, {
  Html,
  Head,
  Main,
  NextScript,
  DocumentContext,
  DocumentInitialProps,
} from "next/document";

export default class MyDocument extends Document {
  static async getInitialProps(
    ctx: DocumentContext,
  ): Promise<DocumentInitialProps> {
    const initialProps = await Document.getInitialProps(ctx);
    return initialProps;
  }

  render() {
    return (
      <Html lang={this.props.locale}>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

Cuando se utiliza la configuración i18n integrada de Next.js, el framework proporciona automáticamente la configuración regional y actualiza el atributo lang. La prop locale está disponible en el componente Document cuando i18n está configurado en next.config.js.