Cómo Implementar Hreflang en Next.js con el App Router

Next.js es la plataforma donde hreflang resulta más limpio: no necesitas plugin, módulo ni librería de SEO. El App Router lo cubre de forma nativa con el campo alternates.languages de generateMetadata. Lo que sí necesitas es tener claro qué URL corresponde a cada idioma, porque el framework se limita a imprimir lo que le pases y no valida nada.

La implementación básica con el App Router

Cualquier layout o page puede exportar generateMetadata. Lo que devuelvas en alternates.languages acaba como etiquetas de alternativa en el head. La clave es que el mismo objeto de idiomas debe ser idéntico en todas las versiones de la página, y debe incluir la propia.

// app/[locale]/servicios/page.tsx
import type { Metadata } from 'next'

const SITE = 'https://ejemplo.com'
const LOCALES = ['es', 'en', 'fr'] as const

export async function generateMetadata({
  params,
}: {
  params: Promise<{ locale: string }>
}): Promise<Metadata> {
  const { locale } = await params

  const languages = Object.fromEntries(
    LOCALES.map((l) => [l, `${SITE}/${l}/servicios`]),
  )

  return {
    alternates: {
      canonical: `${SITE}/${locale}/servicios`,
      languages: {
        ...languages,
        'x-default': `${SITE}/es/servicios`,
      },
    },
  }
}

Como el objeto languages se construye recorriendo la lista completa de idiomas, la autorreferencia y la etiqueta de retorno salen gratis: las tres versiones declaran exactamente el mismo grupo. Es el motivo por el que este patrón falla mucho menos que escribir las etiquetas a mano.

El caso del idioma por defecto sin prefijo

Muchos sitios sirven el idioma principal sin prefijo (ejemplo.com/servicios) y el resto con él (ejemplo.com/en/services). Es la configuración "as-needed" de next-intl. Aquí es donde se rompe la mayoría de implementaciones, porque el segmento del sistema de ficheros sigue siendo [locale] con valor "es" y resulta tentador construir la URL con él.

// Con localePrefix: 'as-needed' y defaultLocale: 'es'
const SITE = 'https://ejemplo.com'

function urlDe(locale: string, ruta: string) {
  // El idioma por defecto NO lleva prefijo en la URL pública,
  // aunque el segmento del router valga 'es'.
  return locale === 'es' ? `${SITE}${ruta}` : `${SITE}/${locale}${ruta}`
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ locale: string }>
}): Promise<Metadata> {
  const { locale } = await params

  return {
    alternates: {
      canonical: urlDe(locale, '/servicios'),
      languages: {
        es: urlDe('es', '/servicios'),
        en: urlDe('en', '/servicios'),
        'x-default': urlDe('es', '/servicios'),
      },
    },
  }
}

Rutas traducidas

Si además traduces el slug —/servicios en español, /services en inglés— no puedes reutilizar la misma ruta para todos los idiomas. Necesitas un mapa explícito por página. next-intl lo resuelve con su configuración de pathnames, pero el principio es el mismo con cualquier enfoque: cada idioma tiene su propia ruta y el grupo hreflang debe reflejarlas.

const RUTAS = {
  es: '/servicios',
  en: '/services',
  fr: '/prestations',
} as const

const languages = Object.fromEntries(
  Object.entries(RUTAS).map(([l, ruta]) => [
    l,
    l === 'es' ? `${SITE}${ruta}` : `${SITE}/${l}${ruta}`,
  ]),
)

Páginas dinámicas

En rutas con parámetros —fichas de producto, artículos— el grupo debe construirse a partir del contenido, no de la lista de idiomas. Si un artículo solo existe en dos de los tres idiomas, el grupo debe tener dos entradas. Declarar un idioma cuya URL no existe genera una etiqueta hacia un 404, y eso invalida el grupo completo.

Qué comprobar cuando ya está desplegado

En Next.js el error casi nunca está en la sintaxis: está en las URLs que has generado. Prefijos de más, rutas sin traducir, idiomas declarados que no existen para ese contenido. Como el framework imprime sin validar, el fallo solo se ve en el HTML servido, y solo comparando las versiones de un mismo grupo entre sí.

Si usas otra plataforma, o quieres el detalle conceptual de qué hace cada atributo:

• Qué es hreflang y cómo implementarlo correctamente
• Los 7 errores de hreflang más comunes y cómo solucionarlos
• Hreflang en WordPress
• Hreflang en Shopify
• Hreflang en sitemap XML para sitios grandes