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:
| Structure | Example |
|---|---|
| Subdirectories | example.com/en/, example.com/de/ |
| Subdomains | en.example.com, de.example.com |
| Country-code domains | example.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
1. Return links
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 likeenglish. - Use ISO 3166-1 alpha-2 region codes after a hyphen:
en-GB, noten-UKand noten_GB. - A region alone is not valid.
GBorUScannot 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.
| Method | Best fit | Watch for |
|---|---|---|
HTML <head> links | Server-rendered or templated pages | Tags must be in the delivered HTML head; large clusters add page weight |
HTTP Link header | Non-HTML files such as PDFs | Header must match across versions; rare in practice |
| XML sitemap | Large sites, or when templates are hard to edit | Every 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.
HTTP Link header
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
| Mistake | What it looks like | Fix |
|---|---|---|
| Missing return link | /en/ lists /de/, but /de/ has no hreflang | Emit the full set on every version |
| No self-reference | /de/ lists /en/ and /fr/ but not itself | Add the page's own URL to its set |
| Invalid code | en-UK, en_GB, eng, GB | en-GB, en; region alone is invalid |
| Combined tags | One <link> carrying several alternates | One <link> per alternate [4] |
| Relative URLs | href="/de/preise/" | Absolute URLs with protocol and host |
| Pointing at redirects or errors | Alternate URL returns 301, 404 or 5xx | Point at final URLs that return 200 |
| Language-based redirects | Visitors bounced by IP or Accept-Language | Serve each URL as-is; offer a switcher [2] |
| Canonical points elsewhere | /de/ canonicalizes to /en/ | Self-canonicalize each language version |
| Mismatched sets | Pages in the same cluster list different alternates | Generate 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.
- 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.
- Link headers.
``bash curl -sI https://example.com/files/guide-de.pdf | grep -i '^link' ``
- Sitemaps. Open the file and confirm each
urlhas the full set with itself included [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.
- 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.
- Spot-check the status of alternates. Request each alternate URL without cookies and without an
Accept-Languageheader, 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
- Confirm each language version has its own crawlable URL, with no forced language redirects.
- Generate one set of alternates per cluster from a single data source, with self-reference and an
x-default. - Validate codes against the
languageorlanguage-REGIONformat. - Make each language version self-canonical.
- Run the curl checks and a crawl, then fix reciprocity gaps and non-200 alternates.