
About
>
name: seo-hreflang description: > Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations. Use when user says "hreflang", "i18n SEO", "international SEO", "multi-language", "multi-region", or "language tags". risk: unknown source: "https://github.com/AgriciDaniel/claude-seo" date_added: "2026-03-21" user-invokable: true argument-hint: "[url]" allowed-tools:
- Read
- Grep
- Glob
- Bash
- WebFetch
Hreflang & International SEO
When to Use
- Use when validating or generating hreflang for multilingual or multiregional sites.
- Use when the user mentions international SEO, language tags, x-default, or hreflang issues.
- Use when auditing locale alternates across HTML, headers, or sitemap implementations.
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:
enginstead ofen(ISO 639-2, not valid for hreflang)jpinstead ofja(incorrect code for Japanese)zhwithout region qualifier (ambiguous; usezh-Hansorzh-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-ukinstead ofen-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=canonicalpointing 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 <head> 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="alter