View contents
Introduction
The hreflang attribute tells Google which language or regional version of a page to show each user, preventing equivalent versions in different languages from competing against each other as if they were duplicate content. The UXR SEO Analyzer validates hreflang implementation: code syntax, presence of return links, and consistency with the canonical tag.
This guide covers the exact syntax, the three implementation methods, the x-default value, the bidirectional link requirement, and the mistakes that most often cause Google to ignore annotations.
Hreflang Syntax
It's declared in the <head> with one <link> tag per language/region version, including a self-reference to the page itself:
<link rel="alternate" hreflang="es-CL" href="https://example.com/cl/" />
<link rel="alternate" hreflang="es-MX" href="https://example.com/mx/" />
<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />The language code follows ISO 639-1 (es, en, pt) and the optional region code follows ISO 3166-1 Alpha 2 (CL, MX, US), separated by a hyphen. The region code is optional but the language code is mandatory; a region code should never be used alone without a language.
Three Implementation Methods
| Method | Where It Lives | When to Use It |
|---|---|---|
<link> tags in the <head> | Each page's HTML | Small to medium sites |
| HTTP header | Server response | Non-HTML resources (PDF) |
| XML sitemap | Sitemap file | Large sites—avoids bloating each page's HTML |
Hreflang and Duplicate Content
Without hreflang, two pages with nearly identical content in the same language but targeting different countries (for example, /us/ and /uk/, both in English) can compete against each other in search results as if they were duplicate content, diluting ranking signals between the two versions. Hreflang resolves this explicitly: it tells Google that both pages are intentional variants of the same content for different audiences, not an accidental duplicate, so they don't penalize each other or compete for the same keywords.
XML Sitemap Implementation for Large Sites
When a site has dozens of language/region versions, declaring hreflang in every page's <head> becomes unmanageable—a page with 10 versions needs 10 <link> tags repeated across each of those 10 pages, meaning 100 synchronized annotations. The XML sitemap centralizes this in a single file:
<url>
<loc>https://example.com/cl/</loc>
<xhtml:link rel="alternate" hreflang="es-MX" href="https://example.com/mx/" />
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/" />
</url>Every URL in the sitemap still needs references to all of its alternates, including a self-reference, but maintenance is centralized in a single programmatically generated file instead of spread across hundreds of HTML templates.
The x-default Value
The reserved x-default value specifies the fallback page for users whose language or region settings don't match any localized version of the site—typically a language selector page or the default global version. It's recommended, though not required, and is declared just like any other hreflang value.
The Most Important Requirement: Bidirectional Return Links
Google has explicitly noted on its developer blog that hreflang annotations must be bidirectional: if page A links to page B as its alternate-language version, page B must link back to page A. If either direction is missing, Google ignores both annotations entirely—not just the missing one. On sites with multiple languages, every page needs a link to every other version, including a self-reference to itself.
Hreflang and the Canonical URL
Every localized version must carry its own self-referencing canonical tag, pointing to itself—never to the version in another language. Confusing these two mechanisms (for example, canonicalizing every language version to the English version) tells Google to ignore the "non-canonical" versions, defeating the purpose of hreflang.
When You Need Hreflang (and When You Don't)
Not every site with more than one language needs hreflang. If the site offers completely different content per language with no equivalent pages across versions, hreflang adds nothing because there's no "alternate" content to annotate. Hreflang becomes necessary when two or more pages are essentially the same piece of content, adapted for a different language or region—exactly the situation where, without the annotation, Google might treat them as competitors or duplicates.
| Scenario | Needs Hreflang? |
|---|---|
| Same article translated into 3 languages | Yes |
| Store with a different product catalog per country | Only on equivalent pages (category, home) |
| Corporate blog in a single language only | No |
| Same English page for the US and the UK with different prices | Yes (en-US vs en-GB) |
Common Mistakes
- Missing return links: the most frequent cause of Google ignoring annotations
- Incorrect language codes: using invented or malformed codes instead of ISO 639-1/3166-1
- Missing self-reference: a page must include itself in its own set of hreflang annotations
- Conflict with canonical: canonicalizing toward a different language version
- URLs that don't resolve with 200: linking to versions that redirect or return an error
- Confusing a language code with a country code: using
CLas if it were a language code instead of a region
Consistency Across Implementation Methods
A site shouldn't mix all three implementation methods (<link> tags, HTTP header, and sitemap) for the same URLs, since contradictory values across methods create the same problem as missing return links: Google may choose to ignore the entire annotation set for that URL. If the site already declares hreflang in the sitemap, there's no need to repeat it in every page's <head>—picking a single method and keeping it consistent reduces the surface for error.
How to Diagnose Hreflang Problems
Search Console's International Targeting report shows site-wide hreflang errors, including missing return links and invalid language codes. At the page level, manually verifying that every URL in the annotation set loads with a 200 status and that its own hreflang set includes a link back is the most reliable way to spot breaks in the bidirectional chain.
Relationship to URL Structure
Hreflang doesn't replace a good international URL structure—it complements it. Whether a site uses subdirectories (/es/, /en/), subdomains (es.example.com), or ccTLDs (example.es, example.de), hreflang is still needed to explicitly connect the equivalent versions to each other. The choice of URL structure affects ease of implementation (subdirectories are usually simpler to maintain than multiple domains) but doesn't remove the need for correct hreflang annotations.
What the UXR SEO Analyzer Checks
The tool validates the format of language/region codes, confirms a self-reference exists, detects when hreflang annotations conflict with the page's canonical tag, and flags when a URL referenced in hreflang doesn't return a successful response.
References
- Google Search Central - Localized Versions of Your Pages
- Google Search Central Blog - Troubleshooting Hreflang Annotations
- Google Search Central Blog - x-default Hreflang for International Pages
- Google Search Central Blog - Unifying Content Under Multilingual Templates