# hreflang

## What it is

Written on a link, `hreflang` states which language the page at the other end is in. HTML allows it on `a`, `area` and `link` elements, but the use that made it well known is a set of `link rel="alternate"` elements in a page's head, one per language version, through which a site tells search engines that several addresses hold the same content in different languages.

```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/" />
```

The HTML standard calls the attribute "purely advisory". Its value "must be a valid BCP 47 language tag", and a browser has to take a fetched page's language from the page itself, never from the link that led there. Combined with `rel="alternate"`, an `hreflang` that differs from the document's own language marks the target as a translation.

Search engines turned that advisory note into a protocol. Google documents three equivalent ways to supply the set: link elements in the head, an HTTP `Link` header for PDFs and other files without one, and entries in an XML sitemap. Each version lists itself as well as every other version, with fully qualified addresses. A pair counts only when both pages name each other, so that another site cannot declare itself a translation of yours. Codes are an ISO 639-1 language, optionally followed by an ISO 3166-1 region, and a region on its own is invalid. The reserved value `x-default` names the page for readers whose language matches none of the others, and Google notes it was designed for language selector pages.

Two neighbours are easy to confuse with it. The `lang` attribute says what language the text in front of the reader is in; `hreflang` says what language a linked page is in. Google states that it uses neither to detect a page's language, so `hreflang` cannot make a page Danish; it tells an engine that a Danish page it already recognises belongs with an English one. And a canonical URL merges duplicates into one indexed address, while `hreflang` identifies language alternatives and helps a search engine choose which version to show.

## Why it matters

The decision `hreflang` records is whether the language versions of a page form one cluster or are judged as separate pages. Left separate, each version competes on its own merits, and an engine may show the English page to a Danish reader, or list both versions in the same results. Declared as a cluster, the versions are understood as one piece of content, and the engine can offer the version that matches the reader's language settings.

The cluster only makes sense when the versions really are the same content. A site in one language needs no `hreflang` at all, and two language sections that differ in substance are not a cluster either. Regional variants with small differences, such as `en-GB` and `en-US` pages that differ in prices, form a cluster too.

The cost is bookkeeping, and it grows with the square of the number of languages. Every version of every page carries the full list, so adding, moving or withdrawing one translation changes the head of every sibling, and a list that is right on most pages and wrong on a few fails quietly: the pairs that point both ways are used and the rest are dropped, with no visible error. That makes `hreflang` a poor fit for hand editing and a natural fit for a generator that derives every page's set from one list. What `hreflang` changes is which of several versions a searcher is shown.

## What it looks like in practice

This site builds its language editions from one content tree, so each page has a set of sibling translations to declare.

One template decides which translations are announced, and several places read it: the `hreflang` set in the head, the `og:locale:alternate` tags used by link previews, the alternates in the sitemap, the `inLanguage` of the site's structured data, and, after one further subtraction, the language strip a reader sees. The list includes the page itself, which supplies the self-reference the rules ask for. The codes name languages only, such as `en`, `da` and `uk`, so each version is offered to every reader of that language wherever they are, and the English entry is written a second time as `x-default`. The head and the sitemap both carry the set, rendered from that one list, so they cannot drift apart.

The split between machines and readers is deliberate. At an earlier implementation stage, the Ukrainian version was announced to crawlers and listed in the sitemaps, while the top-bar language strip omitted it. One configuration flag controlled that distinction: crawlers received reciprocal Ukrainian alternates while only the reader's language strip changed. A second flag, for a language that is built but not ready, removes it from both lists and marks its pages `noindex`. A page in such a language declares no siblings either, because an `hreflang` from an unannounced page to an announced one is a pair an engine sees from only one end.

Copies follow the same reasoning. A page served on one of the focused subdomains, whose canonical points back to the main site, emits no `hreflang` at all: the set is read on the page an engine has accepted as canonical, and a copy naming its own host's translations would contradict the line above it. Its language switcher still works, because a reader who wants Danish should still get Danish.

A check over the built pages asserts that every page with alternates includes `x-default` and its own language, and that every alternate is a built page, is in an announced language and points back. The self-reference rule earns its place. The generator offers two similarly named lists, `.Translations`, which leaves the current page out, and `.AllTranslations`, which includes it, and the one-word slip removes each page's own language from the head and from the language strip at once, leaving the two in agreement. Against a deliberately broken build, that single assertion was the only one in the check to catch 528 of the 792 pages.

## Where it goes wrong

Searchers are shown the version in the wrong language. A Danish reader is sent to the English page, or both versions turn up side by side. The pairs point one way: the Danish page names the English one, but the English page still lists only the languages it had before, and engines ignore a pair that is missing its return link. Build every page's set from one list that includes the page itself, and test reciprocity on the built output.

A whole language's annotations do nothing. The markup is present and valid HTML, yet the versions are treated as unrelated. The codes name the wrong thing: `ua` or `dk` where the languages are `uk` and `da`, `be` meant as Belgium when it is the code for Belarusian, or `en-UK` where `en-GB` was meant, since `UK` is a reserved region code that Google ignores. Use a language from ISO 639-1, add a region from ISO 3166-1 only where the content differs by country, and remember that a valid BCP 47 tag can still be one Google does not support.

Translations drop out of the index. Only the original language appears in search, and the translations are treated as its duplicates. Each translation names the original as its canonical, which asks for the translation to be merged away while its `hreflang` asks for it to be shown. Make every language version its own canonical; Google's guidance is that the canonical should be a page in the same language.

A page that asked to stay out of search is announced anyway. A draft language marked `noindex` appears among the alternates of published pages, or lists them from its own head. The announcement and the directive were set in different places, so the site gives a crawler two answers about the same address. Decide per language, announced in both directions or in neither, put that decision in one setting that every list reads, and check the built pages against it.

## Further reading
* HTML Standard: the hreflang attribute — what the attribute means on a link, and why a browser must not trust it.
* HTML Standard: link type "alternate" — how `hreflang` and `type` describe a translation or another format of the same document.
* RFC 5646: Tags for Identifying Languages — the BCP 47 syntax the attribute's value has to follow.
* Google Search Central: localized versions of your pages — the three delivery methods, the reciprocity rule and `x-default`.

=> /portfolio/built-a-multilingual-hugo-site-in-3-languages/ builds its language editions from one content tree
=> /credits/ the Ukrainian version was announced to crawlers and listed in the sitemaps
=> https://html.spec.whatwg.org/multipage/links.html#attr-hyperlink-hreflang HTML Standard: the hreflang attribute
=> https://html.spec.whatwg.org/multipage/links.html#rel-alternate HTML Standard: link type "alternate"
=> https://www.rfc-editor.org/rfc/rfc5646 RFC 5646: Tags for Identifying Languages
=> https://developers.google.com/search/docs/specialty/international/localized-versions Google Search Central: localized versions of your pages

=> https://engineer.company/glossary/hreflang/ This page on the web
