Hreflang implementation comes down to four rules. Give each language or regional version its own URL. Make every version list every alternate, including itself. Use valid language and region codes. Add one x-default for visitors whose language you do not cover. Google accepts the annotations in HTML <head> tags, HTTP Link headers, or an XML sitemap [1].

Most hreflang failures are inconsistencies between pages in a cluster, not syntax errors. The sections below cover the setup first, then the failures, then how to test.

Start with separate URLs

Google recommends a different URL for each language version, rather than using cookies or browser settings to switch language on one URL [2]. Hreflang annotates URLs, so it needs distinct URLs to point at.

Any of these structures works:

StructureExample
Subdirectoriesexample.com/en/, example.com/de/
Subdomainsen.example.com, de.example.com
Country-code domainsexample.com, example.de

Pick one and keep it consistent. Subdirectories are the simplest to maintain on a single platform.

Avoid redirecting visitors to a language version automatically. Googlebot usually originates from the USA and does not send an Accept-Language header, so dynamic rerouting by language can stop Google from finding all your variations [2]. Show every version at its own URL, and offer a visible language switcher or a suggestion banner instead of a forced redirect.

The three rules every cluster must follow

Each version of a page must link to all the other versions. If page A names page B as an alternate and B does not name A, search engines may ignore the hreflang links or interpret them incorrectly [3]. Think of a cluster as a full set: every member lists every member.

2. Self-reference

Each page must list itself in the set. Google's head-tag, Link-header and sitemap guidance all say to include the page itself among the alternates [1]. A German page lists the English page, the French page, and itself.

3. Valid codes

The format is a language code, optionally followed by a region: en, en-GB, pt-BR, de-AT. This is general practice:

  • Use ISO 639-1 language codes (en, de, pt), not three-letter codes or names like english.
  • Use ISO 3166-1 alpha-2 region codes after a hyphen: en-GB, not en-UK and not en_GB.
  • A region alone is not valid. GB or US cannot stand in for a language.
  • Add a region only when you really publish different content for that region. If you have one English page for everyone, use en.

x-default

Google's hreflang example includes an x-default URL for users whose language is not explicitly listed [1]. It is typically a language selector page or the version you want unmatched visitors to land on.

x-default is an alternate like any other. It must appear in every page's set, and the page it points to must list the full set back. A common setup points x-default at the English version, in which case that page appears twice in its own set, once as en and once as x-default.

Choose a delivery method

Google supports all three methods [1]. Which one fits depends on your stack.

MethodBest fitWatch for
HTML <head> linksServer-rendered or templated pagesTags must be in the delivered HTML head; large clusters add page weight
HTTP Link headerNon-HTML files such as PDFsHeader must match across versions; rare in practice
XML sitemapLarge sites, or when templates are hard to editEvery url entry needs all alternates

HTTP hreflang is almost gone in the wild: 0.2% of desktop pages and 0.1% of mobile pages in the 2025 Web Almanac [5]. For overall adoption, hreflang appeared on about 20.3% of desktop pages and 19.7% of mobile pages in raw crawls [5].

HTML head

<link rel="alternate" hreflang="en" href="https://example.com/en/pricing/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/preise/" />
<link rel="alternate" hreflang="fr-CA" href="https://example.com/fr-ca/tarifs/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/pricing/" />

Each alternate gets its own <link> element. Google's July 31, 2024 documentation update clarified that link tags for alternate versions must not be combined in a single link tag [4]. Use absolute URLs, including protocol, so there is no ambiguity.

The same block goes on every version of the page. Only the page's own URL differs in what it represents, and it is still listed.

The Link header returned for every version of a page should be identical and include every alternate, including the requested page [1].

Link: <https://example.com/files/guide-en.pdf>; rel="alternate"; hreflang="en",
      <https://example.com/files/guide-de.pdf>; rel="alternate"; hreflang="de",
      <https://example.com/files/guide-en.pdf>; rel="alternate"; hreflang="x-default"

XML sitemap

Each url element must include xhtml:link alternates for every version of the page, including itself [1]. That means the same full set is repeated inside every url entry.

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/en/pricing/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing/" />
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise/" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/pricing/" />
  </url>
  <url>
    <loc>https://example.com/de/preise/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing/" />
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise/" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/pricing/" />
  </url>
</urlset>

For general sitemap setup and submission, see the XML sitemap guide. Generate sitemap hreflang from your data source, not by hand. The repetition is what makes manual maintenance fragile.

Common hreflang mistakes

MistakeWhat it looks likeFix
Missing return link/en/ lists /de/, but /de/ has no hreflangEmit the full set on every version
No self-reference/de/ lists /en/ and /fr/ but not itselfAdd the page's own URL to its set
Invalid codeen-UK, en_GB, eng, GBen-GB, en; region alone is invalid
Combined tagsOne <link> carrying several alternatesOne <link> per alternate [4]
Relative URLshref="/de/preise/"Absolute URLs with protocol and host
Pointing at redirects or errorsAlternate URL returns 301, 404 or 5xxPoint at final URLs that return 200
Language-based redirectsVisitors bounced by IP or Accept-LanguageServe each URL as-is; offer a switcher [2]
Canonical points elsewhere/de/ canonicalizes to /en/Self-canonicalize each language version
Mismatched setsPages in the same cluster list different alternatesGenerate every set from one source

Two of these need more explanation.

Canonicals. Hreflang and canonical tags send separate signals. If a German page canonicalizes to the English page, you are telling search engines the German URL is a duplicate, which contradicts listing it as an alternate. Each language version should canonicalize to itself. The canonical tags guide covers how to check which URL Google chose.

Redirecting alternates. An alternate that redirects or returns an error cannot serve as a valid target. Check what each URL in your sets actually returns; the HTTP status codes guide lists what each code tells a crawler.

How to test

Check the annotations the server actually delivers, not the template you think you shipped.

  1. Head tags. Fetch the raw HTML and look at what is in it:

``bash curl -s https://example.com/de/preise/ | grep -i 'hreflang' ``

Compare with the rendered DOM in your browser's inspector. If the tags only appear after JavaScript runs, confirm they are present in the rendered output as well.

  1. Link headers.

``bash curl -sI https://example.com/files/guide-de.pdf | grep -i '^link' ``

  1. Sitemaps. Open the file and confirm each url has the full set with itself included [1].
  1. Lighthouse. The SEO audit "Document doesn't have a valid hreflang" flags invalid hreflang values on a page, and notes that each version must link to all others including itself [3]. It checks one page at a time, so it will not find missing return links across a cluster.
  1. Crawl the cluster. Use a crawler that reads hreflang. Export every URL with its alternates and check three things: every alternate URL returns 200, every pair is reciprocal, and every page includes itself. For a small site, a script that loads each URL's set and compares them is enough.
  1. Spot-check the status of alternates. Request each alternate URL without cookies and without an Accept-Language header, which approximates what Googlebot sends [2]. If you get redirected to a different language, fix that first.

Treat this as an item in your regular technical SEO checklist and re-run it after template changes, new locales or URL restructures. Those are the moments sets drift apart.

What to do next

  1. Confirm each language version has its own crawlable URL, with no forced language redirects.
  2. Generate one set of alternates per cluster from a single data source, with self-reference and an x-default.
  3. Validate codes against the language or language-REGION format.
  4. Make each language version self-canonical.
  5. Run the curl checks and a crawl, then fix reciprocity gaps and non-200 alternates.