What Is Hreflang? Definition, Code Example and Common Mistakes

A website with several language versions runs into a problem search engines cannot solve on their own: how does Google know that the German, Spanish and English versions of a page are the same content, just in a different language? Without an explicit signal, a search engine treats those three URLs as three separate, possibly even competing pages. That is exactly what hreflang addresses. The attribute groups every language version of a page together and, at the same time, states which language and, optionally, which country each version is meant for.

The value of the hreflang attribute follows a fixed syntax: first the language code in ISO 639-1 format, for example "en" for English or "de" for German, optionally followed by a hyphen and the region code in ISO 3166-1 Alpha-2 format, such as "en-GB" for English aimed at the United Kingdom or "es-MX" for Spanish aimed at Mexico. The order is mandatory: language first, region second, never the other way round. A value like "GB-en" is invalid and gets ignored. There is also a special value, "x-default", which marks the version shown when none of the defined language versions match a visitor's language or region, usually the international or English homepage.

The most common way to implement hreflang is as a group of link tags in the head of every page involved. That group must be identical across all versions: every page lists itself and every other version. Here is a complete block for a glossary entry with three language versions plus x-default, using our own domain as the example. The figure below shows the complete block for all three language versions.

This exact block, with the same four hreflang lines and the same canonical tag, needs to sit in the head of all three pages involved, not just the English one. The only thing that changes from page to page is the page's own canonical URL. On sites with many language versions, the head section quickly becomes hard to maintain; in that case, the XML sitemap is the better route, with each URL referencing its alternates through xhtml:link entries. For non-HTML documents such as PDFs, the correct method is the HTTP Link header with rel="alternate", since a PDF has no head section to place tags in.

Which of the three methods to pick depends mostly on the number of pages involved. A site with a few dozen multilingual pages can manage hreflang through link tags in the head without trouble, because mistakes can still be checked by hand. With several hundred or thousand URLs per language, the sitemap approach becomes far easier to maintain, since the mapping can be generated from a single data source instead of being kept in every template. Whichever method is used, the rule stays the same: the group has to be complete and internally consistent, or Google ignores the whole signal for those URLs.

Hreflang and the canonical tag are often confused because both live in the head and both work with URLs. Their jobs, though, are fundamentally different. The canonical tag says: out of several technically similar or identical URLs, this is the one version that should be indexed, for example when the same page is reachable both with and without tracking parameters. Hreflang, on the other hand, says: these pages are deliberately distinct language versions of the same content, all of them should be indexed, but each shown to the audience it is meant for.

Even so, the two signals have to work together. Every language version needs its own canonical tag pointing to itself. If the German version's canonical tag points to the Spanish URL, Google reads that as a signal that only the Spanish page should be indexed, and the entire hreflang group is effectively invalidated, because one of the supposedly equivalent language versions is marking itself as non-canonical. A common and easy-to-miss mistake is that the URL used in the hreflang attribute does not exactly match the URL used in that same page's own canonical tag, for instance because one has a trailing slash and the other does not. To Google those are two different URLs, even if a browser lands on the same page either way. The canonical URL and the hreflang self-reference need to match character for character.

The costliest mistake in practice, and also the hardest to spot, involves redirects. An hreflang link must always point directly to the final URL that returns a 200 status code, never to a URL that is itself a redirect. If an hreflang entry points to an intermediate URL that redirects with a 301 or 302 to some other address, Google does not treat that link as a valid language signal.

Google's official Search Central reference on redirects explains how redirects are handled for indexing purposes: when a redirect exists, Google keeps track of both the source URL and the target URL internally and consolidates ranking signals onto the canonical one, while the other becomes a plain "alternate name" that is no longer considered on its own for indexing (source: developers.google.com/search/docs/crawling-indexing/301-redirects). An hreflang link that points at the redirect source rather than the target is therefore no longer referencing an indexable, canonical page. Google's own hreflang documentation separately and explicitly requires that every language version reference itself and every other version correctly, paired with the right canonical tag (source: developers.google.com/search/docs/specialty/international/localized-versions); a URL that is itself only a redirect cannot meet that requirement of being a stable, canonical destination. Taken together, these two official documentation pages verify the rule beyond doubt: every hreflang link has to point to the actual, live page that answers with 200.

This mistake almost never shows up when a multilingual site is first built. It tends to appear later, after a URL structure change. If, say, a glossary moves from /blog/glossary/term to a shorter URL like /term, and the old address is redirected with a 301 to the new one, the hreflang entries on the other language versions are often left untouched and keep pointing at the now-redirected old address. The page itself keeps working perfectly for visitors, since the redirect does its job, which is exactly why the mistake can go unnoticed for months. It usually only surfaces through Search Console or by crawling the hreflang target URLs directly to check their real status code.

Besides the redirect mistake, three other error types show up regularly in practice, all three explicitly named in Google's own list of common mistakes.

Missing return links are the single most frequent mistake. If the English version links to the Spanish version via hreflang, the Spanish version must link back to the English one, and both must also reference themselves. Google states this plainly in its official documentation: if two pages don't both point to each other, the tags will be ignored. A one-directional link is not a valid hreflang signal as far as Google is concerned, it simply gets skipped.

Incorrect language codes are the second major bucket. It's common to try using a region code without a language code, for example "GB" instead of "en-GB"; Google treats that as invalid, a region code on its own is not accepted. Equally common is reversing the order, for example "GB-en" instead of "en-GB". Both mistakes cause Google to ignore the affected entry.

Invalid region codes are the third bucket: some sites use codes that sound familiar but do not officially belong to ISO 3166-1 Alpha-2, such as "EU" for Europe, "UN" for the United Nations, or "UK" for the United Kingdom, when the correct code is "GB". Reserved or unassigned codes like these are not recognized by Google.

A fourth, less-discussed mistake involves blocked or excluded target pages: if an hreflang link points to a URL blocked by robots.txt or carrying a noindex tag, Google cannot evaluate that version, even if it returns a 200 status. From a search engine's point of view, a blocked page is not a valid target for a language signal, much like with a redirect, there simply is no reachable, indexable destination page.

• Every language version references itself and all other versions, including a consistent x-default for languages or regions not otherwise covered.
• The URL used in hreflang matches the URL used in that page's own canonical tag character for character, including trailing slashes and letter case.
• Every hreflang link points to a URL that returns a 200 status directly, never to a redirect and never to a URL carrying noindex.
• After any URL structure change, every hreflang target URL gets re-checked for its actual status code, not just the new structure itself.
• Language codes follow ISO 639-1, optional region codes follow ISO 3166-1 Alpha-2, always in the order language before region.
• With many language versions, manage hreflang through the XML sitemap rather than individual link tags in the head, which keeps the head lean and cuts down on manual errors.

• An hreflang link points to a URL that itself redirects with a 301 or 302, instead of the final destination page.
• Missing return links: page A links to page B via hreflang, but B does not link back to A.
• Language and region codes swapped, for example "GB-en" instead of "en-GB".
• A region code given without an accompanying language code, which Google does not accept.
• Reserved or invalid region codes such as "EU", "UN" or "UK" used instead of the correct country code.
• The hreflang URL and the canonical URL of the same page differ slightly, for instance through a missing or extra trailing slash.