Saltar al contenido

hreflang en Next.js: cómo declarar un sitio bilingüe (es y en)

En la práctica/ 9 min de lectura

hreflang en Next.js con alternates.languages y el sitemap: etiquetas recíprocas, x-default, es contra es-MX y un script en Node que revisa páginas reales.

  • SEO
  • Next.js
En este artículo (9)
  1. Qué problema resuelve hreflang
  2. Etiquetas recíprocas: cada versión lista a todas
  3. x-default: la versión para cuando nada coincide
  4. Cómo implementarlo en Next.js
  5. es o es-MX: qué código poner
  6. Cómo validar hreflang
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

hreflang le dice a Google cuál es la versión en otro idioma de la página que está leyendo. En Next.js lo declaras con alternates.languages en la metadata de cada página, y cada versión debe listar a todas las demás y a sí misma, con URLs completas y, si quieres, un x-default.

Aquí tienes el código para un sitio en inglés y español, la diferencia entre es y es-MX, y un script en Node que revisa las etiquetas de páginas reales. Corrimos el código con los resolvers de metadata de una instalación de Next.js 15 y el script con el HTML público de ecomlabs.dev.

Qué problema resuelve hreflang

Un sitio bilingüe tiene dos URLs por página: /blog/lcp-hero-image y /es/blog/lcp-imagen-principal-lenta. Para Google son páginas distintas. hreflang le dice que son la misma página en dos idiomas, para que muestre a cada persona la versión que le corresponde. Según Google Search Central, las versiones localizadas solo se consideran duplicadas si el contenido principal sigue sin traducir; si lo tradujiste, no compiten entre sí.

Hay tres formas de declararlo: etiquetas en el HTML, cabeceras HTTP o el sitemap. Google las considera equivalentes, te deja elegir la más cómoda y dice que usar las tres a la vez no aporta nada en Search. En Next.js lo más directo es el HTML con alternates; el sitemap sirve de segundo canal si tienes muchas páginas.

Etiquetas recíprocas: cada versión lista a todas

La regla central de Google: cada versión debe listarse a sí misma y a todas las demás, y si dos páginas no se apuntan una a la otra, las etiquetas se ignoran. Las URLs tienen que ser completas, con https://. Estas son las etiquetas públicas de la versión en inglés de uno de nuestros artículos, tal como salen en su HTML:

<link rel="canonical" href="https://ecomlabs.dev/blog/lcp-hero-image"/>
<link rel="alternate" hrefLang="en" href="https://ecomlabs.dev/blog/lcp-hero-image"/>
<link rel="alternate" hrefLang="es" href="https://ecomlabs.dev/es/blog/lcp-imagen-principal-lenta"/>
<link rel="alternate" hrefLang="x-default" href="https://ecomlabs.dev/blog/lcp-hero-image"/>
  1. canonical apunta a la propia página: cada idioma es canónico de sí mismo, no de la otra versión.
  2. hrefLang="en" es la propia página, porque cada versión debe listarse a sí misma.
  3. hrefLang="es" apunta a la versión en español, con otro slug: los slugs cambian entre idiomas, así que no se construyen sumando un prefijo.
  4. x-default apunta al inglés. La versión en español tiene las mismas tres etiquetas alternate; solo cambia su canonical.
dos versiones que se apuntan una a la otraversión en inglés/blog/hero-imageenesta páginaesla otrax-defaultinglésversión en español/es/blog/imagen-principalenla otraesesta páginax-defaultingléslas dos páginas llevan las mismas tres etiquetassin enlace de vuelta, Google ignora las etiquetaslas URLs deben ser completas, con https://cada versión lista a todas, incluida ella mismaregla de Google Search Central sobre versiones localizadas

Desliza la figura para verla completa

x-default: la versión para cuando nada coincide

El valor reservado x-default se usa cuando ninguna otra versión coincide con el idioma del navegador de quien busca. El ejemplo de Google lo apunta a una página para elegir país. En un sitio de dos idiomas no necesitas esa página: apunta x-default a la versión por defecto, que en el sitio de ejemplo es la inglesa. Google lo describe como el valor para cuando nada coincide y no dice que sea obligatorio, así que el script de abajo lo marca como aviso y no como error.

Cómo implementarlo en Next.js

En el App Router, alternates forma parte del objeto metadata o de generateMetadata (documentación), y Next.js lo convierte en <link rel="alternate" hreflang>. Si usas rutas relativas, define metadataBase en el layout raíz; sin él, una ruta relativa rompe el build. Esta es la ayuda que usamos, junto con una página y el layout:

// lib/hreflang.ts
import type { Metadata } from "next";

export type Locale = "en" | "es";

// English lives at the root and Spanish under /es. Each version's whole path is
// passed in, because the slug can differ between languages.
export function pageAlternates(paths: Record<Locale, string>, current: Locale): Metadata["alternates"] {
  return {
    canonical: paths[current],
    languages: { en: paths.en, es: paths.es, "x-default": paths.en },
  };
}

// app/blog/[slug]/page.tsx (the English page; the Spanish page passes "es")
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug); // { slug: { en, es } } from your data layer
  return {
    title: post.title,
    alternates: pageAlternates(
      { en: `/blog/${post.slug.en}`, es: `/es/blog/${post.slug.es}` },
      "en",
    ),
  };
}

// app/layout.tsx: lets the relative paths above resolve to full URLs
export const metadata: Metadata = { metadataBase: new URL("https://example.com") };
  1. pageAlternates recibe la ruta de cada idioma y el idioma actual, y devuelve el objeto alternates.
  2. canonical es la ruta de la página actual: cada versión es canónica de sí misma.
  3. languages lista en, es y x-default. Como la misma lista sale en ambas páginas, la reciprocidad queda garantizada por construcción.
  4. generateMetadata busca el artículo y arma las dos rutas con el slug de cada idioma.
  5. metadataBase completa las rutas relativas hasta URLs absolutas.

Con esta ayuda, los resolvers de Next.js generaron las cuatro etiquetas del ejemplo anterior, con example.com como base. El sitemap es el segundo canal. Desde la v14.2.0, cada entrada acepta alternates.languages (documentación del sitemap):

// app/sitemap.ts
import type { MetadataRoute } from "next";

const BASE = "https://example.com";

// One entry per page, with the path of each language version.
const pages = [
  { en: "/", es: "/es" },
  { en: "/services", es: "/es/servicios" },
];

export default function sitemap(): MetadataRoute.Sitemap {
  return pages.flatMap((p) => {
    const languages = { en: BASE + p.en, es: BASE + p.es, "x-default": BASE + p.en };
    // Both versions get a <url>, and both carry the same full list.
    return [
      { url: languages.en, alternates: { languages } },
      { url: languages.es, alternates: { languages } },
    ];
  });
}
  1. pages guarda la ruta de cada versión; las URLs deben ser absolutas, aquí con BASE.
  2. languages es la lista completa de la página, con la propia versión incluida. El ejemplo de la documentación de Next.js solo lista es y de para la URL base; como Google pide que cada versión se liste a sí misma, aquí añadimos también en.
  3. El flatMap escribe un <url> por versión, y las dos llevan la misma lista.

La función generó un <url> por versión, con un xhtml:link por cada entrada de languages.

un sitio, dos árboles de URLs enlazados par a paringlés · raízespañol · /eshreflang//es/services/es/servicios/blog/es/blog/blog/lcp-hero-image/es/blog/lcp-imagen-principal-lentax-default → la versión en inglés de cada parlos slugs cambian entre idiomas: /services y /es/servicioscada URL sabe cuál es su parpares reales de un sitio bilingüe, etiquetas públicas

Desliza la figura para verla completa

es o es-MX: qué código poner

Según Google, el primer código es el idioma, en formato ISO 639-1, y el segundo, opcional, la región, en ISO 3166-1 alfa-2. Puedes usar solo el idioma; no puedes usar solo el país; y códigos que no estén en esos estándares, como es-419, no se admiten. Por eso es cubre todo el español y es-MX solo tiene sentido si de verdad tienes una versión para México distinta de otra para el resto: entonces listas ambas, como en el ejemplo de Google con en-GB, en-US y en.

Código¿Se admite?Cuándo
esSíTodo el español, sin región
es-MXSíUna versión específica para México
es-419NoNo es ISO 639-1 más ISO 3166-1
MXNoLa región no puede ir sola
x-defaultSí (reservado)Cuando ninguna otra versión coincide

Ojo: los tipos de Next.js no te protegen. Probamos languages: { "es-419": "/es" } con tsc --strict y compila sin quejas, porque el tipo acepta cualquier xx-algo. El error aparece en Google, no en tu editor.

códigos de hreflang: cuáles se admitencódigo¿se admite?cuándoessítodo el español, sin regiónes-MXsíuna versión para Méxicoes-419nono es ISO 639-1 + ISO 3166-1MXnola región no puede ir solax-defaultsí (reservado)ninguna otra versión coincidelos tipos de Next.js aceptan es-419: compila, Google no lo admiteidioma ISO 639-1, región ISO 3166-1 opcionalfuente: Google Search Central, versiones localizadas

Desliza la figura para verla completa

Cómo validar hreflang

Un script en Node sin dependencias, check-hreflang.mjs, lee el HTML guardado de cada página que le pases y comprueba lo que pide Google: que haya etiquetas, que los códigos sean válidos, que las URLs sean completas, que la página se liste a sí misma y que las demás páginas del lote le apunten de vuelta. Sin x-default avisa, no falla. El script completo va en la guía. Esto dio con el HTML público guardado de dos páginas del sitio y con una página rota que escribimos a mano:

$ node check-hreflang.mjs fixtures/home.html fixtures/home-es.html
OK   fixtures/home.html
OK   fixtures/home-es.html

$ node check-hreflang.mjs fixtures/home.html fixtures/broken-es.html
FAIL fixtures/home.html
     - es -> https://ecomlabs.dev/es: that page does not link back
FAIL fixtures/broken-es.html
     - unsupported code "es-419"
     - href is not fully qualified: "/es"
     - the page does not list itself
     ! no x-default
  1. El primer lote es la portada en inglés y en español: las dos pasan.
  2. El segundo lote cambia la portada en español por una página rota, broken-es.html, que escribimos con un código no admitido y una URL relativa.
  3. La portada en inglés falla porque lista a /es y esa página no le apunta de vuelta.
  4. La página rota acumula tres errores y el aviso de x-default.

También pasaron la portada, el blog y un artículo con su par en español, y las etiquetas que genera el código de arriba. En producción, abre la página, mira el HTML fuente y pasa el script por cada tipo de página.

Errores comunes

  • Etiquetas sin enlace de vuelta. Si dos páginas no se apuntan, Google las ignora.
  • No listar la propia página. Cada versión debe incluirse a sí misma.
  • URLs relativas. Deben ser completas con https://; en metadata, metadataBase las completa.
  • Canonical de la versión en español hacia el inglés. Le dices a Google que una es copia de la otra; cada idioma debe ser canónico de sí mismo.
  • Códigos no admitidos como es-419 o una región sola. TypeScript los deja pasar.
  • Construir la URL del otro idioma con un prefijo. Si el slug cambia, el enlace apunta a una página que no existe; guarda la ruta de cada idioma.
  • Declarar una versión que no existe. Esa URL no te apuntará de vuelta, así que la etiqueta se ignora.

Preguntas frecuentes

¿Necesito hreflang si mi sitio solo tiene dos idiomas?

Si las dos versiones existen como páginas separadas, sí es útil: es el método que documenta Google para declararlas como equivalentes. Sin él, cada página se evalúa por su cuenta.

¿HTML, sitemap o cabecera HTTP?

Google dice que los tres métodos son equivalentes y que usarlos todos no aporta nada en Search. En Next.js, alternates en la metadata es lo más simple. El sitio de ejemplo publica etiquetas en el HTML y también en el sitemap, pero con uno basta.

¿Qué pasa si falta el enlace de vuelta en una de las páginas?

Google ignora las etiquetas de las dos. Por eso conviene generar la lista desde un solo lugar, como pageAlternates, en lugar de escribirla a mano en cada página.

¿Dónde apunto x-default si no tengo una página para elegir idioma?

A la versión por defecto. El sitio de ejemplo lo apunta a la versión en inglés de cada página. Google lo describe como el valor para cuando ningún idioma coincide.

Checklist

  • Cada página lista todas sus versiones y a sí misma, con URLs completas.
  • La lista sale de un solo lugar y las dos versiones usan la misma.
  • Cada idioma tiene su propio canonical.
  • x-default apunta a la versión por defecto.
  • Usas es, o es-MX solo si hay una versión para México; nada de es-419.
  • Los slugs de cada idioma se guardan, no se calculan con un prefijo.
  • metadataBase está en el layout raíz.
  • El script pasa en una página de cada tipo.

Con hreflang bien puesto, Google sabe qué versión mostrar. Para que además entienda qué vendes, revisa los datos estructurados de producto.

¿Viste esto en Instagram? Comenta HREFLANG en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 12 de noviembre de 2026 · actualizado el 18 de noviembre de 2026

← Blog