- Hreflang & International SEO
- Validate existing hreflang implementations or generate correct hreflang tags
- for multi-language and multi-region sites. Supports HTML, HTTP header, and
- XML sitemap implementations.
- Validation Checks
- 1. Self-Referencing Tags
- Every page must include an hreflang tag pointing to itself
- The self-referencing URL must exactly match the page's canonical URL
- Missing self-referencing tags cause Google to ignore the entire hreflang set
- 2. Return Tags
- If page A links to page B with hreflang, page B must link back to page A
- Every hreflang relationship must be bidirectional (A→B and B→A)
- Missing return tags invalidate the hreflang signal for both pages
- Check all language versions reference each other (full mesh)
- 3. x-default Tag
- Required: designates the fallback page for unmatched languages/regions
- Typically points to the language selector page or English version
- Only one x-default per set of alternates
- Must also have return tags from all other language versions
- 4. Language Code Validation
- Must use ISO 639-1 two-letter codes (e.g.,
- en
- ,
- fr
- ,
- de
- ,
- ja
- )
- Common errors:
- eng
- instead of
- en
- (ISO 639-2, not valid for hreflang)
- jp
- instead of
- ja
- (incorrect code for Japanese)
- zh
- without region qualifier (ambiguous — use
- zh-Hans
- or
- zh-Hant
- )
- 5. Region Code Validation
- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g.,
- en-US
- ,
- en-GB
- ,
- pt-BR
- )
- Format:
- language-REGION
- (lowercase language, uppercase region)
- Common errors:
- en-uk
- instead of
- en-GB
- (UK is not a valid ISO 3166-1 code)
- es-LA
- (Latin America is not a country — use specific countries)
- Region without language prefix
- 6. Canonical URL Alignment
- Hreflang tags must only appear on canonical URLs
- If a page has
- rel=canonical
- pointing elsewhere, hreflang on that page is ignored
- The canonical URL and hreflang URL must match exactly (including trailing slashes)
- Non-canonical pages should not be in any hreflang set
- 7. Protocol Consistency
- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)
- Mixed HTTP/HTTPS in hreflang sets causes validation failures
- After HTTPS migration, update all hreflang tags to HTTPS
- 8. Cross-Domain Support
- Hreflang works across different domains (e.g., example.com and example.de)
- Cross-domain hreflang requires return tags on both domains
- Verify both domains are verified in Google Search Console
- Sitemap-based implementation recommended for cross-domain setups
- Common Mistakes
- Issue
- Severity
- Fix
- Missing self-referencing tag
- Critical
- Add hreflang pointing to same page URL
- Missing return tags (A→B but no B→A)
- Critical
- Add matching return tags on all alternates
- Missing x-default
- High
- Add x-default pointing to fallback/selector page
- Invalid language code (e.g.,
- eng
- )
- High
- Use ISO 639-1 two-letter codes
- Invalid region code (e.g.,
- en-uk
- )
- High
- Use ISO 3166-1 Alpha-2 codes
- Hreflang on non-canonical URL
- High
- Move hreflang to canonical URL only
- HTTP/HTTPS mismatch in URLs
- Medium
- Standardize all URLs to HTTPS
- Trailing slash inconsistency
- Medium
- Match canonical URL format exactly
- Hreflang in both HTML and sitemap
- Low
- Choose one method — sitemap preferred for large sites
- Language without region when needed
- Low
- Add region qualifier for geo-targeted content
- Implementation Methods
- Method 1: HTML Link Tags
- Best for: Sites with <50 language/region variants per page.
- <
- link
- rel
- =
- "
- alternate
- "
- hreflang
- =
- "
- en-US
- "
- href
- =
- "
- https://example.com/page
- "
- />
- <
- link
- rel
- =
- "
- alternate
- "
- hreflang
- =
- "
- en-GB
- "
- href
- =
- "
- https://example.co.uk/page
- "
- />
- <
- link
- rel
- =
- "
- alternate
- "
- hreflang
- =
- "
- fr
- "
- href
- =
- "
- https://example.com/fr/page
- "
- />
- <
- link
- rel
- =
- "
- alternate
- "
- hreflang
- =
- "
- x-default
- "
- href
- =
- "
- https://example.com/page
- "
- />
- Place in
- section. Every page must include all alternates including itself.
- Method 2: HTTP Headers
- Best for: Non-HTML files (PDFs, documents).
- Link: https://example.com/page; rel="alternate"; hreflang="en-US",
- https://example.com/fr/page; rel="alternate"; hreflang="fr",
- https://example.com/page; rel="alternate"; hreflang="x-default"
- Set via server configuration or CDN rules.
- Method 3: XML Sitemap (Recommended for large sites)
- Best for: Sites with many language variants, cross-domain setups, or 50+ pages.
- See Hreflang Sitemap Generation section below.
- Method Comparison
- Method
- Best For
- Pros
- Cons
- HTML link tags
- Small sites (<50 variants)
- Easy to implement, visible in source
- Bloats
- , hard to maintain at scale
- HTTP headers
- Non-HTML files
- Works for PDFs, images
- Complex server config, not visible in HTML
- XML sitemap
- Large sites, cross-domain
- Scalable, centralized management
- Not visible on page, requires sitemap maintenance
- Hreflang Generation
- Process
- Detect languages
-
- Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
- Map page equivalents
-
- Match corresponding pages across languages/regions
- Validate language codes
-
- Verify all codes against ISO 639-1 and ISO 3166-1
- Generate tags
-
- Create hreflang tags for each page including self-referencing
- Verify return tags
-
- Confirm all relationships are bidirectional
- Add x-default
-
- Set fallback for each page set
- Output
- Generate implementation code (HTML, HTTP headers, or sitemap XML) Hreflang Sitemap Generation Sitemap with Hreflang
< urlset xmlns = " http://www.sitemaps.org/schemas/sitemap/0.9 " xmlns: xhtml = " http://www.w3.org/1999/xhtml "
< url
< loc
https://example.com/page </ loc
< xhtml: link rel = " alternate " hreflang = " en-US " href = " https://example.com/page " /> < xhtml: link rel = " alternate " hreflang = " fr " href = " https://example.com/fr/page " /> < xhtml: link rel = " alternate " hreflang = " de " href = " https://example.de/page " /> < xhtml: link rel = " alternate " hreflang = " x-default " href = " https://example.com/page " /> </ url
< url
< loc
https://example.com/fr/page </ loc
< xhtml: link rel = " alternate " hreflang = " en-US " href = " https://example.com/page " /> < xhtml: link rel = " alternate " hreflang = " fr " href = " https://example.com/fr/page " /> < xhtml: link rel = " alternate " hreflang = " de " href = " https://example.de/page " /> < xhtml: link rel = " alternate " hreflang = " x-default " href = " https://example.com/page " /> </ url
</ urlset
Key rules: Include the xmlns:xhtml namespace declaration Every
entry must include ALL language alternates (including itself) Each alternate must appear as a separate entry with its own full set Split at 50,000 URLs per sitemap file Output Hreflang Validation Report Summary Total pages scanned: XX Language variants detected: XX Issues found: XX (Critical: X, High: X, Medium: X, Low: X) Validation Results Language URL Self-Ref Return Tags x-default Status en-US https://... ✅ ✅ ✅ ✅ fr https://... ❌ ⚠️ ✅ ❌ de https://... ✅ ❌ ✅ ❌ Generated Hreflang Tags HTML tags (if HTML method chosen) HTTP header values (if header method chosen) hreflang-sitemap.xml (if sitemap method chosen) Recommendations Missing implementations to add Incorrect codes to fix Method migration suggestions (e.g., HTML → sitemap for scale)