{"canonical_url":"https://engineer.company/glossary/hreflang/","content_markdown":"# hreflang\n\n## What it is\n\nWritten on a link, `hreflang` states which language the page at the other end is\nin. HTML allows it on `a`, `area` and `link` elements, but the use that made it\nwell known is a set of `link rel=\"alternate\"` elements in a page's head, one per\nlanguage version, through which a site tells search engines that several\naddresses hold the same content in different languages.\n\n```html\n\u003clink rel=\"alternate\" hreflang=\"en\" href=\"https://example.com/guide/\" /\u003e\n\u003clink rel=\"alternate\" hreflang=\"da\" href=\"https://example.com/da/guide/\" /\u003e\n\u003clink rel=\"alternate\" hreflang=\"x-default\" href=\"https://example.com/guide/\" /\u003e\n```\n\nThe HTML standard calls the attribute \"purely advisory\". Its value \"must be a\nvalid BCP 47 language tag\", and a browser has to take a fetched page's language\nfrom the page itself, never from the link that led there. Combined with\n`rel=\"alternate\"`, an `hreflang` that differs from the document's own language\nmarks the target as a translation.\n\nSearch engines turned that advisory note into a protocol. Google documents three\nequivalent ways to supply the set: link elements in the head, an HTTP `Link`\nheader for PDFs and other files without one, and entries in an XML sitemap. Each\nversion lists itself as well as every other version, with fully qualified\naddresses. A pair counts only when both pages name each other, so that another\nsite cannot declare itself a translation of yours. Codes are an ISO 639-1\nlanguage, optionally followed by an ISO 3166-1 region, and a region on its own\nis invalid. The reserved value `x-default` names the page for readers whose\nlanguage matches none of the others, and Google notes it was designed for\nlanguage selector pages.\n\nTwo neighbours are easy to confuse with it. The `lang` attribute says what\nlanguage the text in front of the reader is in; `hreflang` says what language a\nlinked page is in. Google states that it uses neither to detect a page's\nlanguage, so `hreflang` cannot make a page Danish; it tells an engine that a\nDanish page it already recognises belongs with an English one. And a canonical\nURL merges duplicates into one indexed address, while `hreflang` identifies language alternatives and helps a search engine\nchoose which version to show.\n\n## Why it matters\n\nThe decision `hreflang` records is whether the language versions of a page form\none cluster or are judged as separate pages. Left separate, each version\ncompetes on its own merits, and an engine may show the English page to a Danish\nreader, or list both versions in the same results. Declared as a cluster, the\nversions are understood as one piece of content, and the engine can offer the\nversion that matches the reader's language settings.\n\nThe cluster only makes sense when the versions really are the same content. A\nsite in one language needs no `hreflang` at all, and two language sections that\ndiffer in substance are not a cluster either. Regional variants with small\ndifferences, such as `en-GB` and `en-US` pages that differ in prices, form a\ncluster too.\n\nThe cost is bookkeeping, and it grows with the square of the number of\nlanguages. Every version of every page carries the full list, so adding, moving\nor withdrawing one translation changes the head of every sibling, and a list\nthat is right on most pages and wrong on a few fails quietly: the pairs that\npoint both ways are used and the rest are dropped, with no visible error. That\nmakes `hreflang` a poor fit for hand editing and a natural fit for a generator\nthat derives every page's set from one list. What `hreflang` changes is which of\nseveral versions a searcher is shown.\n\n## What it looks like in practice\n\nThis site\n[builds its language editions from one content tree](/portfolio/built-a-multilingual-hugo-site-in-3-languages/),\nso each page has a set of sibling translations to declare.\n\nOne template decides which translations are announced, and several places read it:\nthe `hreflang` set in the head, the `og:locale:alternate` tags used by link\npreviews, the alternates in the sitemap, the `inLanguage` of the site's\nstructured data, and, after one further subtraction, the language strip a reader\nsees. The list includes the page itself, which supplies the self-reference the\nrules ask for. The codes name languages only, such as `en`, `da` and `uk`, so each\nversion is offered to every reader of that language wherever they are, and the\nEnglish entry is written a second time as `x-default`. The head and the sitemap\nboth carry the set, rendered from that one list, so they cannot drift apart.\n\nThe split between machines and readers is deliberate. At an earlier implementation stage,\n[the Ukrainian version was announced to crawlers and listed in the sitemaps](/credits/),\nwhile the top-bar language strip omitted it. One configuration flag controlled that\ndistinction: crawlers received reciprocal Ukrainian alternates while only the reader's\nlanguage strip changed. A second flag, for a language that is built\nbut not ready, removes it from both lists and marks its pages `noindex`. A page\nin such a language declares no siblings either, because an `hreflang` from an\nunannounced page to an announced one is a pair an engine sees from only one end.\n\nCopies follow the same reasoning. A page served on one of the focused\nsubdomains, whose canonical points back to the main site, emits no `hreflang` at\nall: the set is read on the page an engine has accepted as canonical, and a copy\nnaming its own host's translations would contradict the line above it. Its\nlanguage switcher still works, because a reader who wants Danish should still\nget Danish.\n\nA check over the built pages asserts that every page with alternates includes\n`x-default` and its own language, and that every alternate is a built page, is\nin an announced language and points back. The self-reference rule earns its\nplace. The generator offers two similarly named lists, `.Translations`, which\nleaves the current page out, and `.AllTranslations`, which includes it, and the\none-word slip removes each page's own language from the head and from the\nlanguage strip at once, leaving the two in agreement. Against a deliberately\nbroken build, that single assertion was the only one in the check to catch 528\nof the 792 pages.\n\n## Where it goes wrong\n\n**Searchers are shown the version in the wrong language.** A Danish reader is\nsent to the English page, or both versions turn up side by side. The pairs point\none way: the Danish page names the English one, but the English page still lists\nonly the languages it had before, and engines ignore a pair that is missing its\nreturn link. Build every page's set from one list that includes the page itself,\nand test reciprocity on the built output.\n\n**A whole language's annotations do nothing.** The markup is present and valid\nHTML, yet the versions are treated as unrelated. The codes name the wrong thing:\n`ua` or `dk` where the languages are `uk` and `da`, `be` meant as Belgium when\nit is the code for Belarusian, or `en-UK` where `en-GB` was meant, since `UK` is\na reserved region code that Google ignores. Use a language from ISO 639-1, add a\nregion from ISO 3166-1 only where the content differs by country, and remember\nthat a valid BCP 47 tag can still be one Google does not support.\n\n**Translations drop out of the index.** Only the original language appears in\nsearch, and the translations are treated as its duplicates. Each translation\nnames the original as its canonical, which asks for the translation to be merged\naway while its `hreflang` asks for it to be shown. Make every language version\nits own canonical; Google's guidance is that the canonical should be a page in\nthe same language.\n\n**A page that asked to stay out of search is announced anyway.** A draft\nlanguage marked `noindex` appears among the alternates of published pages, or\nlists them from its own head. The announcement and the directive were set in\ndifferent places, so the site gives a crawler two answers about the same\naddress. Decide per language, announced in both directions or in neither, put\nthat decision in one setting that every list reads, and check the built pages\nagainst it.\n\n## Further reading\n\n- [HTML Standard: the hreflang attribute](https://html.spec.whatwg.org/multipage/links.html#attr-hyperlink-hreflang)\n  — what the attribute means on a link, and why a browser must not trust it.\n- [HTML Standard: link type \"alternate\"](https://html.spec.whatwg.org/multipage/links.html#rel-alternate)\n  — how `hreflang` and `type` describe a translation or another format of the\n  same document.\n- [RFC 5646: Tags for Identifying Languages](https://www.rfc-editor.org/rfc/rfc5646)\n  — the BCP 47 syntax the attribute's value has to follow.\n- [Google Search Central: localized versions of your pages](https://developers.google.com/search/docs/specialty/international/localized-versions)\n  — the three delivery methods, the reciprocity rule and `x-default`.\n\n\u003chttps://engineer.company/glossary/hreflang/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How hreflang links the language versions of a page, why every set must name itself and point both ways, and the codes and gaps that get it ignored.","formats":{"gemtext":"https://engineer.company/glossary/hreflang/index.gmi","gopher":"https://engineer.company/glossary/hreflang/gophermap","html":"https://engineer.company/glossary/hreflang/","json":"https://engineer.company/glossary/hreflang/index.json","markdown":"https://engineer.company/glossary/hreflang/index.md","pdf":"https://engineer.company/glossary/hreflang/index.pdf"},"kind":"page","language":"en","title":"What is hreflang?","url":"https://engineer.company/glossary/hreflang/","version":1}