SEO2,556 words

How to implement hreflang tags correctly, with examples

How to implement hreflang tags: codes, the three methods, return links, x-default, canonicals and a worked example cluster.

ContentsWhat do hreflang tags actually do?

On this page0% read

how to implement hreflang tags examples

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; gb is read as a language code, and there is no such language.
  • The United Kingdom is gb, so en-uk is wrong: Google ignores the uk part, so the page is not targeted at the UK.
  • Use a hyphen, not an underscore. en_GB is 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-Hant for 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.

MethodBest forWatch out for
HTML link elementsMost CMS sites with a manageable number of versions per pageAdds a line per version to every page head; templates must output the full set on every locale
HTTP Link headerNon-HTML files such as PDFs, where there is no head to put tags inInvisible in view-source; set at server or CDN level, so easy to forget during migrations
XML sitemapLarge sites, many locales, or when you cannot edit page templatesEvery 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.

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:

AudiencehreflangURL
English, United Kingdomen-gbhttps://example.com/uk/
English, United Statesen-ushttps://example.com/us/
German, any countrydehttps://example.com/de/
Everyone elsex-defaulthttps://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 de pointing at /de/).
  • Every pair is reciprocal, because the same block appears on all four pages.
  • Codes are valid: en-gb rather than en-uk, and de with 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

MistakeWhat happensFix
No return link from an alternateGoogle ignores the annotations between those pagesPublish the identical set on every version
Missing self-referenceThe set is incompleteInclude the current page in its own list
en-uk instead of en-gbGoogle ignores the region part, so the page is not targeted at the UKUse ISO 3166-1 codes: the UK is gb
Region on its own, such as usRead as a language code that does not existPrefix the language: en-us
Relative URLs such as /de/The annotation is not acceptedWrite full URLs including https://
Alternates that redirectThe annotated URL is not the page that gets indexedPoint at the final URL; check chains with the redirect checker
Alternates that are noindexed or canonicalised elsewhereYou are annotating pages Google is told not to indexMake every version indexable and self-canonical
Two methods with different setsConflicting signals that are hard to debugUse one method per cluster
The same code pointing at two URLsUnclear which URL to serveOne 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.

  1. 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.
  2. 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.
  3. 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.
  4. Fix canonicals. Make sure each version canonicalises to itself and returns 200 without redirecting.
  5. 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.
  6. 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.
  7. 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.

Keep reading

All SEO articles

Want this applied to your site?

A free 30-minute call with Sakshi Kumari or Ashish Khan, the specialists who run MoxSEO. Bring your site and your numbers; they will tell you what to fix first and what the data cannot tell you.

A call is not an engagement. SEO plans start at $584 a month, and we never guarantee rankings.

How the call works

  1. Send your siteBook a slot and tell us which SEO questions you want answered for your site.
  2. We review it firstBefore the call we look at crawl health, indexation and AI citation coverage on your pages.
  3. Thirty minutes, ranked fixesYou leave knowing what to fix first and why. No proposal unless you ask for one.