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

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, 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 difiere. 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 páginas para la audiencia del idioma correcto, reduciendo la capacidad de descubrimiento para usuarios que buscan en ese idioma.

Solución

Configura 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 e indexación precisa.

Pasos

1. Crea 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 en 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 configura el atributo de idioma en el elemento HTML raíz. Reemplaza "en" con el código de idioma de tu contenido.

2. Utiliza el código de idioma apropiado

Los códigos de idioma siguen el formato estándar UTS Locale Identifiers: language-region-script, donde región y script son opcionales. Para la mayoría de los casos, utiliza 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 enrutador para establecer el idioma de forma dinámica.

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 usas 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.