# hreflang

## Qué es

Escrito en un enlace, `hreflang` indica en qué idioma está la página de destino. HTML lo permite en los elementos `a`, `area` y `link`, pero su uso más conocido es un conjunto de elementos `link rel="alternate"` en la cabecera de una página, uno por versión lingüística, con el que un sitio comunica a los buscadores que varias direcciones contienen el mismo contenido en idiomas distintos.

```html
<link rel="alternate" hreflang="en" href="https://example.com/guide/" />
<link rel="alternate" hreflang="da" href="https://example.com/da/guide/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/guide/" />
```

El estándar HTML llama al atributo «meramente orientativo». Su valor «debe ser una etiqueta de idioma BCP 47 válida» y, al obtener una página, el navegador debe determinar su idioma a partir de ella misma, nunca del enlace que llevó a ella. Combinado con `rel="alternate"`, un `hreflang` distinto del idioma del documento marca el destino como traducción.

Los buscadores convirtieron esa nota orientativa en un protocolo. Google documenta tres formas equivalentes de proporcionar el conjunto: elementos de enlace en la cabecera, una cabecera HTTP `Link` para PDF y otros archivos sin cabecera HTML, y entradas en un sitemap XML. Cada versión se enumera a sí misma y a todas las demás con direcciones absolutas completas. Una pareja solo cuenta si ambas páginas se nombran mutuamente, para que otro sitio no pueda declararse traducción del suyo. Los códigos son un idioma ISO 639-1 seguido opcionalmente de una región ISO 3166-1; una región por sí sola no es válida. El valor reservado `x-default` nombra la página para lectores cuyo idioma no coincide con ninguno de los otros y Google señala que se diseñó para páginas de selección de idioma.

Es fácil confundirlo con dos conceptos próximos. El atributo `lang` dice en qué idioma está el texto que ve el lector; `hreflang` dice el idioma de una página enlazada. Google declara que no usa ninguno para detectar el idioma: `hreflang` no convierte una página en danés, sino que comunica que una página danesa ya reconocida pertenece al mismo conjunto que una inglesa. Una URL canónica fusiona duplicados en una dirección indexada; `hreflang` identifica las alternativas lingüísticas y ayuda al buscador a elegir qué versión mostrar.

## Por qué importa

La decisión que registra `hreflang` es si las versiones lingüísticas de una página forman un conjunto o se evalúan como páginas separadas. Si se mantienen separadas, cada una compite por sus propios méritos y el buscador puede mostrar la inglesa a un lector danés o ambas en los mismos resultados. Si se declaran como conjunto, se entienden como un mismo contenido y el buscador puede ofrecer la versión que coincide con el idioma configurado por el lector.

El conjunto solo tiene sentido si las versiones son realmente el mismo contenido. Un sitio monolingüe no necesita `hreflang`, y dos secciones lingüísticas que difieren en lo sustancial tampoco forman un conjunto. Sí lo forman variantes regionales con pequeñas diferencias, como páginas `en-GB` y `en-US` con precios distintos.

El coste es mantener el registro y crece con el cuadrado del número de idiomas. Cada versión de cada página lleva la lista completa: añadir, mover o retirar una traducción cambia la cabecera de todas sus hermanas. Una lista correcta en la mayoría de las páginas y equivocada en unas pocas falla en silencio: se usan las parejas con enlaces en ambos sentidos y se descarta el resto, sin error visible. Eso hace que `hreflang` encaje mal con la edición manual y bien con un generador que derive el conjunto de cada página de una lista. Lo que cambia `hreflang` es cuál de varias versiones se muestra a quien busca.

## Cómo se aplica en la práctica

Este sitio [construye sus ediciones lingüísticas desde un único árbol de contenido](/es/portfolio/built-a-multilingual-hugo-site-in-3-languages/), por lo que cada página tiene un conjunto de traducciones hermanas que declarar.

Una plantilla decide qué traducciones se anuncian y varios lugares la consultan: el conjunto `hreflang` de la cabecera, las etiquetas `og:locale:alternate` de las vistas previas, las alternativas del sitemap, el campo `inLanguage` de los datos estructurados y, tras una exclusión adicional, la franja de idiomas que ve el lector. La lista incluye la propia página y aporta así la autorreferencia requerida. Los códigos nombran solo idiomas, por ejemplo `en`, `da` y `uk`, de modo que cada versión se ofrece a todos los lectores de ese idioma, estén donde estén; la entrada inglesa se escribe otra vez como `x-default`. Cabecera y sitemap llevan el conjunto generado desde esa misma lista, así que no pueden divergir.

La separación entre máquinas y lectores es deliberada. En una etapa anterior de la implementación, [la versión ucraniana se anunciaba a los rastreadores y se enumeraba en los sitemaps](/es/credits/), mientras la franja de idiomas de la barra superior la omitía. Una sola bandera de configuración controlaba esa distinción: los rastreadores recibían alternativas ucranianas recíprocas y solo cambiaba la franja de idiomas del lector. Una segunda bandera, para un idioma cuya edición se construye pero aún no está lista, lo retira de ambas listas y marca sus páginas como `noindex`. Una página de ese idioma tampoco declara hermanas, porque un `hreflang` de una página no anunciada a una anunciada es una pareja que el buscador solo ve desde un extremo.

Las copias siguen el mismo razonamiento. Una página de un subdominio especializado cuya URL canónica apunta al sitio principal no emite ningún `hreflang`: el conjunto se lee en la página aceptada como canónica y una copia que nombrara traducciones de su propio host contradiría la línea anterior. Su selector de idioma sigue funcionando, porque quien quiere danés debe seguir recibiendo danés.

Una comprobación de las páginas construidas verifica que cada página con alternativas incluya `x-default` y su propio idioma, y que cada alternativa sea una página construida, en un idioma anunciado y con enlace de vuelta. La regla de autorreferencia se justifica por sí misma. El generador ofrece dos listas de nombre parecido: `.Translations`, que omite la página actual, y `.AllTranslations`, que la incluye. Confundir esos nombres elimina a la vez el idioma propio de cada página de la cabecera y la franja, que siguen coincidiendo. Ante una construcción alterada deliberadamente, esta fue la única aserción del control que detectó el fallo en 528 de las 792 páginas.

## Dónde surgen los problemas

**Quien busca recibe la versión en el idioma equivocado.** Un lector danés llega a la inglesa o ambas aparecen juntas. Las parejas apuntan en un solo sentido: la danesa nombra la inglesa, pero esta aún enumera solo sus idiomas anteriores, y los buscadores ignoran una pareja sin enlace de vuelta. Genere el conjunto de cada página desde una lista que incluya la propia página y pruebe la reciprocidad sobre la salida construida.

**Las anotaciones de todo un idioma no hacen nada.** El marcado existe y es HTML válido, pero las versiones se tratan como independientes. Los códigos nombran lo equivocado: `ua` o `dk` donde los idiomas son `uk` y `da`, `be` por Bélgica cuando es el código del bielorruso, o `en-UK` donde se quería `en-GB`, ya que `UK` es un código regional reservado que Google ignora. Use un idioma ISO 639-1 y añada una región ISO 3166-1 solo si el contenido cambia por país; recuerde que una etiqueta BCP 47 válida puede no estar admitida por Google.

**Las traducciones desaparecen del índice.** Solo aparece el idioma original en búsquedas y las traducciones se tratan como duplicados. Cada traducción nombra el original como canónico y pide así que la traducción se fusione con él y deje de indexarse por separado, mientras su `hreflang` pide que se muestre. Haga que cada versión sea su propia canónica; Google aconseja que la página canónica esté en el mismo idioma.

**Se anuncia una página que pidió no aparecer en búsquedas.** Un idioma en borrador marcado `noindex` figura entre las alternativas de páginas publicadas o las enumera en su cabecera. El anuncio y la directiva se fijaron en sitios distintos, por lo que el rastreador recibe dos respuestas sobre una dirección. Decida por idioma si se anuncia en ambos sentidos o en ninguno, reúna esa decisión en un ajuste que consulten todas las listas y verifique que las páginas construidas respeten ese ajuste.

## Lecturas adicionales

- [Estándar HTML: atributo hreflang](https://html.spec.whatwg.org/multipage/links.html#attr-hyperlink-hreflang)
  — Significado del atributo en un enlace y por qué el navegador no debe fiarse de él.
- [Estándar HTML: tipo de enlace «alternate»](https://html.spec.whatwg.org/multipage/links.html#rel-alternate)
  — Cómo `hreflang` y `type` describen una traducción u otro formato del mismo documento.
- [RFC 5646: etiquetas para identificar idiomas](https://www.rfc-editor.org/rfc/rfc5646)
  — La sintaxis BCP 47 que debe seguir el valor del atributo.
- [Google Search Central: versiones localizadas de sus páginas](https://developers.google.com/search/docs/specialty/international/localized-versions)
  — Las tres formas de entrega, la regla de reciprocidad y `x-default`.

<https://engineer.company/es/glossary/hreflang/>
