
To implement hreflang tags correctly, list every language or regional version of a page, give each one a valid code, and publish the same complete set of annotations on every version, including a reference to itself. Each version must canonicalise to itself, every alternate must link back, and the whole set goes in one place: the HTML head, HTTP headers or your XML sitemap. Then check the live pages, because hreflang fails silently.
Short answer: hreflang tells Google which URL to show a searcher based on their language and, optionally, their region. Write one annotation per version using an ISO 639-1 language code and an optional ISO 3166-1 Alpha 2 region (en-gb, not en-uk), add x-default for visitors who match none of them, and put the identical set on every page in the cluster. The hreflang tag generator checks the codes and writes the block for you in HTML, sitemap or header format.
What do hreflang tags actually do?
An hreflang annotation says: this page has an equivalent in another language or region, and here is its URL. Google can then swap in the most suitable version, so a searcher in Vienna gets your German page rather than the English one that happened to rank.
It is worth being precise about what it does not do, because most disappointment with hreflang comes from expecting too much:
- It does not make a page rank in a market where it has no visibility. It chooses between your own versions; it does not create demand or authority.
- It does not tell Google what language a page is in. Google’s documentation says it detects the language of a page from its content, not from hreflang or the lang attribute.
- It does not redirect anyone. Visitors who land on the wrong version still need a way to switch, such as a visible language selector.
The other point to absorb early is that hreflang works as a cluster, not page by page. If one page in the set does not confirm the relationship, the annotations between those pages are ignored. We cover that failure mode in detail in why hreflang fails across the entire cluster.
Hreflang code format: language, region and script
Each hreflang value starts with a language code and can add a region. The rules are short and strict.
- Language is required and uses ISO 639-1:
en,de,fr,es. - Region is optional and uses ISO 3166-1 Alpha 2, after a hyphen:
en-gb,en-us,de-at. - A region cannot stand alone.
hreflang="gb"is not valid;gbis read as a language code, and there is no such language. - The United Kingdom is
gb, soen-ukis wrong: Google ignores theukpart, so the page is not targeted at the UK. - Use a hyphen, not an underscore.
en_GBis a locale string from software, not an hreflang value. - Script variants can be given with an ISO 15924 subtag where the script matters, for example
zh-Hantfor Traditional Chinese.
Only add a region when the page is genuinely aimed at one country. A German page for German speakers everywhere is better as de than de-de, so a searcher in Switzerland still matches.
The three ways to implement hreflang, and when to use each
Google’s documentation describes three methods and treats them as equivalent: link elements in the HTML head, Link headers in the HTTP response, and alternate entries in an XML sitemap. Pick the one your stack can maintain reliably and use only that for the cluster. Mixing methods adds no strength, only more places for the sets to drift apart.
| Method | Best for | Watch out for |
|---|---|---|
| HTML link elements | Most CMS sites with a manageable number of versions per page | Adds a line per version to every page head; templates must output the full set on every locale |
| HTTP Link header | Non-HTML files such as PDFs, where there is no head to put tags in | Invisible in view-source; set at server or CDN level, so easy to forget during migrations |
| XML sitemap | Large sites, many locales, or when you cannot edit page templates | Every URL entry must repeat the full set; sitemap generators often omit the self-reference |
Method 1: link elements in the HTML head
Each version gets one link element per alternate, inside the <head>. URLs must be fully qualified, including https://; a relative path such as /de/ is not accepted.
<link rel="alternate" hreflang="en-gb" href="https://example.com/uk/" />
<link rel="alternate" hreflang="en-us" href="https://example.com/us/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />Method 2: HTTP Link headers
For a PDF or other non-HTML file, send the annotations in a Link response header. Each alternate is a comma-separated entry with rel="alternate" and its hreflang value.
Link: <https://example.com/uk/guide.pdf>; rel="alternate"; hreflang="en-gb",
<https://example.com/us/guide.pdf>; rel="alternate"; hreflang="en-us",
<https://example.com/de/guide.pdf>; rel="alternate"; hreflang="de"Because headers never appear in the page source, treat them the way you would any header-level directive: check the actual response for the exact URL. The same blind spot catches people out with a noindex sent as an X-Robots-Tag header.
Method 3: alternates in the XML sitemap
In a sitemap, declare the xhtml namespace, then give each <url> entry an xhtml:link child for every version in the cluster, including the URL in that entry’s own <loc>. One version per <url>, each repeating the full set.
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://example.com/uk/</loc>
<xhtml:link rel="alternate" hreflang="en-gb" href="https://example.com/uk/" />
<xhtml:link rel="alternate" hreflang="en-us" href="https://example.com/us/" />
<xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/" />
</url>
<!-- repeat the same four xhtml:link lines in the <url> entries
for /us/, /de/ and the x-default page -->
</urlset>If you take this route, run the file through the XML sitemap validator too, so a malformed sitemap does not take the annotations down with it.
Self-reference and return links: the two rules that break most clusters
Google’s documentation says each language version must list itself as well as all other versions. It looks redundant, which is exactly why it gets left out. If the UK page lists the US and German pages but not itself, the set is incomplete.
The second rule is reciprocity. If two pages do not both point to each other, Google’s documentation says the tags will be ignored. When the UK page names the German page as its de alternate, the German page must name the UK page as its en-gb alternate. It usually breaks when one locale is migrated or rebuilt on its own.
The simplest way to satisfy both rules is to treat the set as one shared block: generate it once, publish it identically on every version, and update it everywhere whenever a version is added, removed or moved.
How does hreflang x-default work?
x-default is a reserved hreflang value for the page to show when a searcher’s language and region match none of your listed versions. Google’s documentation says it was designed for language or country selector pages and works best with those, though you can point it at any page, such as your main international version.
It is optional. Without it, matched versions still work, but Google’s documentation recommends it as the fallback for searchers whose language settings match none of your versions. Two practical points:
- The x-default URL can also be one of your language versions. Pointing it at your English global page is common and perfectly valid.
- It belongs in every version’s set, just like the other alternates, and the x-default page itself should carry the full set too.
Google’s documentation recommends x-default for home pages that redirect visitors automatically, but advises against redirecting users from one language version to another. If your root URL redirects visitors by IP or browser language, Googlebot may only ever see one version. Our guide to international SEO and hreflang at the edge explains how to suggest versions to people without hiding them from crawlers.
How hreflang interacts with canonical tags
Each language or regional version should have a canonical tag pointing to itself. The canonical says which URL represents this content; hreflang says which other URLs are its equivalents in other languages. They work together only when every hreflang URL is also a canonical URL.
The mistake to avoid is canonicalising every version to one “main” page, typically the US English one. That tells Google the others are duplicates, so the alternates you annotated are pages you have asked Google not to index separately. The same goes for hreflang URLs that redirect or carry noindex: point annotations at the final, indexable, self-canonical URL.
A worked hreflang example: one cluster, end to end
Take an illustrative shop at example.com selling the same product in three markets, with a language selector on the root:
| Audience | hreflang | URL |
|---|---|---|
| English, United Kingdom | en-gb | https://example.com/uk/ |
| English, United States | en-us | https://example.com/us/ |
| German, any country | de | https://example.com/de/ |
| Everyone else | x-default | https://example.com/ |
Every one of the four pages carries the same block in its head, plus a self-referencing canonical. Here is the full head excerpt for the German page:
<head>
<link rel="canonical" href="https://example.com/de/" />
<link rel="alternate" hreflang="en-gb" href="https://example.com/uk/" />
<link rel="alternate" hreflang="en-us" href="https://example.com/us/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />
</head>The UK page is identical apart from its canonical, which points to https://example.com/uk/. Checking the cluster against the rules:
- Every page lists itself (the German page includes
depointing at/de/). - Every pair is reciprocal, because the same block appears on all four pages.
- Codes are valid:
en-gbrather thanen-uk, anddewith no region because the page serves all German speakers.
If the shop later adds fr at /fr/, the new line goes on all five pages. Adding it only to the French page is how clusters quietly stop working.
Common hreflang mistakes and how to fix them
| Mistake | What happens | Fix |
|---|---|---|
| No return link from an alternate | Google ignores the annotations between those pages | Publish the identical set on every version |
| Missing self-reference | The set is incomplete | Include the current page in its own list |
en-uk instead of en-gb | Google ignores the region part, so the page is not targeted at the UK | Use ISO 3166-1 codes: the UK is gb |
Region on its own, such as us | Read as a language code that does not exist | Prefix the language: en-us |
Relative URLs such as /de/ | The annotation is not accepted | Write full URLs including https:// |
| Alternates that redirect | The annotated URL is not the page that gets indexed | Point at the final URL; check chains with the redirect checker |
| Alternates that are noindexed or canonicalised elsewhere | You are annotating pages Google is told not to index | Make every version indexable and self-canonical |
| Two methods with different sets | Conflicting signals that are hard to debug | Use one method per cluster |
| The same code pointing at two URLs | Unclear which URL to serve | One URL per hreflang value |
Redirecting alternates usually creep in during migrations, when an old path is redirected but the annotations are never updated. Our post on redirect chains and crawl budget covers finding and flattening them.
How to implement hreflang tags, step by step
This process works the same for three versions or thirty.
- Inventory the cluster. For one piece of content, list every version that is a genuine equivalent, with its exact canonical URL. Leave out pages that are not real counterparts.
- Assign codes. Language first, region only when the page targets one country. Decide on an x-default page if you have a selector or global version.
- Generate the annotations. Enter one code and URL per line in the hreflang tag generator, add the x-default URL in its own field, and choose HTML tags, sitemap entries or HTTP headers. It checks codes against ISO 639-1 and ISO 3166-1, flags
en-uk, region-only codes, duplicates and repeated URLs, and refuses relative URLs. It does not fetch anything, so it cannot confirm the pages exist. - Fix canonicals. Make sure each version canonicalises to itself and returns 200 without redirecting.
- Deploy the same block everywhere. Put the identical output on every version, through your template, server config or sitemap generator. Do not hand-edit individual locales.
- Validate the live pages. Run one URL from each locale through the hreflang validator. It checks the page’s hreflang link tags for code format, duplicates, relative URLs, self-reference and x-default, then fetches up to five alternates to confirm each links back. It reads HTML tags only, so check header or sitemap implementations directly.
- Monitor in Search Console. Use URL Inspection to confirm Google selected the canonical you declared for each version, watch the Page indexing report for versions where Google chose a different canonical, and filter the Performance report by country and page to see which version each market is shown. The old International Targeting report has been retired.
Re-run the validation whenever a locale is migrated or a version is added. Most broken clusters were correct at launch and drifted later.
When to get help
For a handful of versions on one CMS, the steps above are enough. Estates with several domains, mixed CMSs or edge routing are where sets drift, and diagnosing them means crawling every locale. If that is your situation, our international SEO service covers hreflang audits and implementation.
What is the correct hreflang format?
A language code in ISO 639-1, optionally followed by a hyphen and a region code in ISO 3166-1 Alpha 2, for example en, de or en-gb. A region cannot be used without a language, and the United Kingdom is gb, so en-uk is invalid.
Do hreflang tags need to be on every page?
Every page that has language or regional equivalents needs the full set, including a reference to itself. Pages with no equivalents do not need hreflang.
Is x-default required?
No. x-default is optional. It names the page to show when a searcher’s language and region match none of your versions, typically a language selector. Leaving it out does not break the rest of the cluster.
Should I use HTML tags, HTTP headers or a sitemap for hreflang?
Google treats them as equivalent. Use HTML tags for most sites, HTTP headers for non-HTML files such as PDFs, and the sitemap for large sites. Use one method per cluster.
Should hreflang pages canonicalise to the main language version?
No. Each version should have a self-referencing canonical. Canonicalising every version to one main page tells Google the others are duplicates, which undermines the hreflang annotations pointing at them.
Why is Google ignoring my hreflang tags?
Usually missing return links, a missing self-reference, invalid codes such as en-uk, relative URLs, or alternates that redirect, are noindexed or canonicalise elsewhere. Check a page from every locale, because the error is often on an alternate.






