If you run a website that targets users in different countries or languages, hreflang tags tell search engines which version of a page to show to which audience. They’re snippets of code that map the relationship between your pages – “this is the English UK version, this is the English US version, this is the French version” – so Google can serve the right one in the right market.
That sounds straightforward. In practice, hreflang is one of the most error-prone elements in international SEO. Google introduced hreflang annotations back in 2011 to help webmasters manage multilingual content, and over a decade later, they’re still consistently misconfigured. The gap between understanding what hreflang does and implementing it correctly is where most sites fall down. This guide bridges that gap – covering all three implementation methods, the mistakes that break things, and a debugging workflow for when something isn’t working.
What Are Hreflang Tags and Why Do They Matter?
Hreflang tags (formally rel="alternate" hreflang) are HTML annotations that tell search engines about the language and regional targeting of a page. They define the relationship between different versions of the same content across languages or regions.
Here’s why they matter for SEO. Without hreflang, Google has to guess which version of your content to show a user in a given country. Sometimes it guesses right. But when you have near-identical pages targeting different English-speaking markets – UK, US, Australia – Google often consolidates them or serves the wrong version. That means your carefully localised UK page gets shown to American users, or your US pricing page appears in Australian search results.
Hreflang solves three specific problems:
Correct geo-targeting. Users see the version of your page written for their language and region. A searcher in Germany gets the German page. A searcher in Brazil gets the Portuguese one.
Duplicate content signals. When you have the same content in multiple regional versions (especially same-language variants like en-GB and en-US), hreflang tells Google these are intentional alternatives, not duplicates. This matters for how Google handles duplicate content across your domains.
Crawl and index efficiency. Instead of Google trying to work out which of your five English pages to index, hreflang provides that map explicitly.
Worth noting: hreflang is primarily a Google and Yandex signal. Bing uses a different system – the content-language meta tag and language declarations in Bing Webmaster Tools. If you’re targeting markets where Bing has meaningful share, you’ll need both approaches.
How Do Language and Region Codes Work?
Hreflang values use a specific format: a language code, optionally followed by a region code. Get these wrong and the tags do nothing.
Language codes follow the ISO 639-1 standard. These are two-letter codes: en for English, fr for French, de for German, es for Spanish, pt for Portuguese, ja for Japanese. You must always include a language code.
Region codes follow the ISO 3166-1 Alpha-2 standard. These are also two-letter codes: GB for the United Kingdom, US for the United States, DE for Germany, BR for Brazil, AU for Australia. Region codes are optional but useful when you have the same language targeting different countries.
The format is: language-REGION. Examples:
en-GB– English, United Kingdomen-US– English, United Statesfr-FR– French, Francefr-CA– French, Canadapt-BR– Portuguese, Brazilde– German (no specific region)
A few things to get right. The language code is always lowercase. The region code is always uppercase. You can use a language code on its own (en, fr, de) but you cannot use a region code without a language code – GB on its own is invalid. And you can’t target a region without specifying a language, because hreflang defines language-region pairs, not just locations.
The Three Implementation Methods
There are three ways to implement hreflang: HTML <link> elements in the page head, HTTP headers, and XML sitemaps. All three do the same job. Which one you pick depends on your site’s technical setup and scale.
Method 1: HTML Link Elements
This is the most common approach. You add <link> elements to the <head> section of each page, listing every language-region variant including the page itself.
For a page with UK English, US English, and French versions:
<head>
<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page/" />
<link rel="alternate" hreflang="en-US" href="https://example.com/page/" />
<link rel="alternate" hreflang="fr" href="https://example.fr/page/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page/" />
</head>Every version of the page carries the full set of hreflang tags – including a tag pointing to itself. That self-referencing tag is mandatory. More on why shortly.
When to use this method: Standard HTML sites, CMS-managed sites where you can edit the <head> section, and sites with a manageable number of language variants per page. It works well for most sites, but it adds markup to every page load, which becomes cumbersome at scale.
Method 2: HTTP Headers
If a page isn’t an HTML document – think PDFs, downloadable files, or non-HTML resources – you can’t put <link> tags in the head because there is no head. HTTP headers solve this.
The server sends hreflang information as part of the HTTP response header:
HTTP/1.1 200 OK
Link: <https://example.co.uk/document.pdf>; rel="alternate"; hreflang="en-GB",
<https://example.com/document.pdf>; rel="alternate"; hreflang="en-US",
<https://example.fr/document.pdf>; rel="alternate"; hreflang="fr",
<https://example.com/document.pdf>; rel="alternate"; hreflang="x-default"When to use this method: Non-HTML resources (PDFs, downloadable files) or when your server setup makes header-level control easier than template-level changes. Rare in practice for most sites. The syntax is also harder to audit because you can’t just view page source.
Method 3: XML Sitemaps
Instead of adding hreflang annotations to every page, you can declare them all in your XML sitemap. Each URL entry includes xhtml:link elements listing its alternates:
<?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.co.uk/page/</loc>
<xhtml:link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page/" />
<xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page/" />
<xhtml:link rel="alternate" hreflang="fr" href="https://example.fr/page/" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page/" />
</url>
<url>
<loc>https://example.com/page/</loc>
<xhtml:link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page/" />
<xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page/" />
<xhtml:link rel="alternate" hreflang="fr" href="https://example.fr/page/" />
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page/" />
</url>
</urlset>Notice that every URL listed in the sitemap also includes itself in its own set of xhtml:link entries. Same self-referencing rule applies.
When to use this method: Large sites with hundreds or thousands of pages. The sitemap approach keeps hreflang out of your page templates, centralises management, and doesn’t add markup to page load times. It’s the most practical option at scale and the easiest to generate programmatically.
Which Method Should You Choose?
The decision is simpler than it looks:
- Small to medium site (under ~200 pages)? HTML
<link>elements. Easiest to implement, easiest to check. - Large site (hundreds or thousands of pages)? XML sitemaps. Centralised management, no template bloat, easier to automate.
- Non-HTML files? HTTP headers. The only option that works.
- Mixed content types? You can combine methods. Use HTML tags for standard pages and HTTP headers for PDFs. Don’t declare the same page’s hreflang in both the HTML head and the sitemap, though – pick one to avoid conflicting signals.
What Is the x-default Tag?
The x-default hreflang value is your catch-all. It tells search engines which page to show when a user doesn’t match any of your specified language-region combinations.
<link rel="alternate" hreflang="x-default" href="https://example.com/page/" />Say you have pages targeting en-GB, en-US, and fr. A user searching from Japan in Japanese won’t match any of those. Without x-default, Google picks whichever version it thinks is most relevant. With it, you control the fallback – usually your main international page or your language selector.
It’s also commonly used for your homepage language picker or a generic English version that isn’t region-specific. Google’s documentation is clear that x-default is optional, but in practice it’s a sensible inclusion on every set of hreflang tags. Treat it as standard.
Why Self-Referencing and Return Links Matter
Two rules that trip up nearly every first-time hreflang implementation: self-referencing tags and bidirectional (return) links.
Self-Referencing Tags
Every page must include an hreflang tag that points to itself. If your UK English page at https://example.co.uk/page/ lists alternates for the US and French versions, it must also include:
<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page/" />Without this, Google can’t confirm that the page recognises itself as part of the hreflang set. Missing self-referencing tags are one of the most common reasons hreflang silently fails.
Bidirectional (Return) Links
Hreflang only works when the relationship is confirmed in both directions. If Page A says “Page B is my French alternate,” Page B must also say “Page A is my English alternate.” If either side is missing the reference, Google ignores the entire pairing.
Think of it as a handshake. Both pages have to agree on the relationship. A one-sided declaration gets dismissed. This bidirectional requirement is often where things break, especially when different teams manage different regional sites independently. The UK team adds hreflang tags. The French team doesn’t. Nothing works.
How Do Hreflang Tags Interact with Canonical Tags?
This is where it gets tricky, and where conflicting directives become a common problem.
Canonical tags and hreflang tags serve different purposes. Canonical says “this is the primary version of this page.” Hreflang says “these are the equivalent pages for other languages or regions.” They should work together, not against each other.
The rule is simple: every page’s canonical tag should point to itself (a self-referencing canonical), and the hreflang tags should point between the different language/region versions. Problems happen when:
- A canonical tag on your French page points to the English page. This tells Google to ignore the French page entirely – overriding the hreflang that says “this is the French version.”
- All regional variants canonicalise to a single “master” page. Google will consolidate to that page and ignore your hreflang annotations.
- Canonical URLs don’t match the hreflang URLs. If your canonical says
https://example.com/pagebut your hreflang sayshttps://example.com/page/(trailing slash difference), they’re treated as different URLs.
The fix is consistency. Canonical tags self-reference. Hreflang tags cross-reference between variants. URLs match exactly across both sets of tags. When these three conditions are met, the two systems complement each other perfectly.
Hreflang Tags Are Hints, Not Directives
Google’s John Mueller and Gary Illyes have both confirmed publicly that hreflang annotations are treated as hints. Google takes them into account alongside other signals – geo-targeting settings in Search Console, server location, ccTLD usage, content language, internal linking patterns – and makes its own decision.
What does this mean in practice? It means hreflang doesn’t guarantee anything. If your hreflang says a page targets German users but the content is in English, Google won’t play along. If your geo-targeting in Search Console contradicts your hreflang, Google will weigh both signals and pick the one it trusts more.
This “hints, not directives” status also means that hreflang can’t fix fundamental problems. If your site structure, content, and other signals all point in a different direction, a hreflang tag won’t override them. Hreflang works best when it confirms what the rest of your setup already implies. It works badly as a band-aid over a messy international site architecture.
When Should You Actually Use Hreflang Tags?
Hreflang isn’t something every site needs. Here’s when it genuinely matters:
- Same content in multiple languages. You have an English page and a French translation. Hreflang maps the relationship.
- Same language, different regions. English for the UK, English for the US, English for Australia. Without hreflang, Google often consolidates these because the content is so similar.
- Regional variations with different pricing, laws, or contact details. Even if the core content is similar, localised details make each version distinct for its audience.
- Multi-domain or subdomain international setups. When your UK site is on a
.co.uk, your US site on.com, and your German site on.de, hreflang ties them together as a family.
When NOT to Use Hreflang Tags
This gets overlooked. Not every international scenario calls for hreflang:
- Single-language, single-region site. You only serve one market in one language. No alternates exist, so hreflang has nothing to map.
- Machine-translated pages you don’t maintain. If auto-translated pages exist but aren’t actively maintained or quality-checked, pointing Google at them via hreflang can hurt more than it helps.
- Pages that differ so much they aren’t really equivalents. Hreflang is for page-level equivalents. If your UK product page has completely different products to your US page, they’re not alternates – they’re different pages. Hreflang doesn’t apply.
- Using hreflang instead of proper geo-targeting. Hreflang handles language and region signals, but it’s not a substitute for correct ccTLD usage, Search Console geo-targeting, or server-level configuration.
Common Implementation Mistakes
Hreflang has more ways to go wrong than most technical SEO elements. Here are the ones that cause real damage.
Missing Return Links
Page A references Page B, but Page B doesn’t reference Page A. Google ignores the annotation for that pair. This is the single most common hreflang error, and it usually happens when one regional team implements hreflang and another doesn’t.
Invalid Language or Region Codes
Using en-UK instead of en-GB (there’s no UK in ISO 3166-1). Using jp instead of ja for Japanese (the language code is ja; jp is the country code). Any invalid code means the tag gets ignored silently – no error, no warning, just no effect.
URLs That Don’t Match
The URL in your hreflang tag must match exactly what Google has indexed. If Google indexes https://example.com/page/ with a trailing slash and your hreflang references https://example.com/page without one, they don’t match. Same goes for protocol (HTTP vs HTTPS) and www vs non-www.
Hreflang on Non-Canonical URLs
If a page has a canonical tag pointing somewhere else, any hreflang on that page is effectively invisible. Google follows the canonical first. Only the canonical version’s hreflang annotations matter.
Missing Self-Referencing Tags
Already covered, but it bears repeating. Every page in an hreflang set must reference itself. Leaving this out is easy and breaks the whole set.
Pointing to Redirecting or Non-200 URLs
Every URL in your hreflang annotations should return a 200 status code. Pointing to a URL that 301-redirects, 404s, or 410s means Google can’t confirm the relationship. It’ll drop the annotation.
A Practical Debugging Workflow
When hreflang isn’t working – the wrong country version shows up in search results, or Search Console reports hreflang errors – here’s a step-by-step way to find the problem.
Step 1: Check what Google actually sees. Use Google Search Console’s URL Inspection tool on the affected page. Look at the “Page indexing” section for any hreflang-related warnings or errors. Check whether Google’s selected canonical matches what you expect.
Step 2: Validate the source markup. View the page source (or HTTP headers, or sitemap) and confirm the hreflang tags are present, correctly formatted, and using valid language-region codes. Check for typos – hreflang="en-BG" (Bulgaria) when you meant en-GB (Great Britain) is an easy one to miss.
Step 3: Verify return links. For every page referenced in the hreflang set, visit that page and confirm it references every other page in the set – including the page you started from. One missing return link breaks the pair.
Step 4: Check canonical alignment. On every page in the set, confirm the canonical tag is self-referencing and the canonical URL matches the URL used in the hreflang annotations exactly.
Step 5: Confirm indexability. Make sure every URL in the hreflang set is indexable. Not blocked by robots.txt, not noindexed, not redirecting. Run a crawl or check each URL’s status code.
Step 6: Wait. Hreflang changes take time to process. Google needs to recrawl every page in the set, and that can take days to weeks depending on crawl frequency. Don’t panic if changes aren’t reflected immediately.
This workflow catches the vast majority of hreflang issues. If everything checks out and the problem persists, you may be dealing with Google overriding your hints based on conflicting signals elsewhere on the site – technical SEO auditing at that point is worth the investment.
Hreflang at Scale: Performance and Maintenance
For sites with hundreds or thousands of pages across multiple regions, hreflang becomes a maintenance challenge. A site with 500 pages targeting five regions has 2,500 hreflang relationships to manage. Add a new region and every existing page needs updating.
Keeping It Manageable
Use the sitemap method. At scale, XML sitemaps are the only practical approach. They centralise all hreflang declarations, can be generated programmatically from a database or CMS, and don’t add markup weight to every page.
Automate generation. Never maintain hreflang tags manually on a large site. Use your CMS, a build process, or a script that generates the sitemap from a single source of truth – typically a database mapping each page to its regional equivalents.
Audit regularly. Pages get added, removed, and redirected. A URL that existed last month might 404 now, and if it’s still referenced in hreflang tags across your other regional sites, the entire set breaks. Schedule quarterly audits at minimum. Tools like Screaming Frog, Ahrefs, and Sitebulb can crawl your hreflang annotations and flag broken references, missing return links, and invalid codes.
Version your sitemap. If you’re generating sitemaps automatically, keep a version history. When something breaks, you want to compare the current sitemap to the previous version and spot what changed.
Subdomain, Subdirectory, or ccTLD?
Your URL structure for international content affects how hreflang is implemented, but not whether it works. Hreflang functions identically across ccTLDs (example.co.uk), subdomains (uk.example.com), and subdirectories (example.com/uk/). The choice between these structures has its own set of trade-offs around link equity, crawl management, and geo-targeting signals – but that’s a separate decision from hreflang itself.
Auditing Tools Worth Knowing
You don’t need to check hreflang manually across hundreds of pages. These tools automate the heavy lifting:
- Screaming Frog SEO Spider. Crawls your site and reports on hreflang implementation – missing return links, invalid codes, non-matching canonicals, the lot. The hreflang report is one of its most useful features.
- Ahrefs Site Audit. Flags hreflang errors as part of its broader technical audit. Good for ongoing monitoring if you’re already using the platform.
- Google Search Console. The URL Inspection tool and indexing reports can surface hreflang-related issues. Limited but free.
- Merkle Hreflang Tag Testing Tool. A free online tool for validating individual pages. Paste a URL, and it checks whether the hreflang implementation is correct, including return links.
- Sitebulb. Strong visual reporting on hreflang relationships. Particularly helpful for seeing the full map of which pages connect to which.
Real-World Examples
A few patterns from well-known international sites that illustrate hreflang in practice:
IKEA uses subdirectories on a single domain (ikea.com/gb/en/, ikea.com/de/de/, ikea.com/fr/fr/) with hreflang mapping between equivalent product and content pages. Each regional page self-references and cross-references, with x-default pointing to the global ikea.com.
HubSpot targets language without region specificity in some cases (hreflang="es" for Spanish rather than "es-ES" or "es-MX"), using x-default for the English version. This works when you have one Spanish page serving all Spanish-speaking markets rather than separate regional variants.
Both approaches work. The consistency of implementation matters far more than which URL structure or hreflang method you pick.
Getting Hreflang Right the First Time
Hreflang isn’t difficult in concept. Language code, region code, point pages at each other, make sure it’s bidirectional. The difficulty is in the details – exact URL matching, valid codes, self-referencing tags, canonical alignment, and maintaining all of it as your site changes.
If you’re launching a new international site, set up hreflang as part of the initial build rather than retrofitting it later. If you’ve got an existing multi-region site with ranking problems, an hreflang audit is often the fastest route to identifying what’s going wrong. Either way, the debugging workflow above will get you most of the way there. For sites where the complexity is beyond what you want to manage in-house, our SEO team works across multi-region setups regularly and can handle the implementation end to end.
