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:
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 <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="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 <head>, 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
<?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.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
<url> entry must include ALL language alternates (including itself)
- Each alternate must appear as a separate
<url> 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
<link> 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 to sitemap for scale)
Error Handling
| Scenario |
Action |
| URL unreachable (DNS failure, connection refused) |
Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. |
| No hreflang tags found |
Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. |
| Invalid language/region codes detected |
List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. |
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Source: sickn33/agentic-awesome-skills → skills/seo-hreflang/SKILL.md
Also appears in: sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills/skills/seo-hreflang/SKILL.md, sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills-claude/skills/seo-hreflang/SKILL.md, sickn33/agentic-awesome-skills/plugins/agentic-bundle-aas-localization-international-growth/skills/seo-hreflang/SKILL.md
1---2name: seo-hreflang3description: > 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".4---5
6
7# Hreflang & International SEO
8
9## When to Use
10- Use when validating or generating hreflang for multilingual or multiregional sites.
11- Use when the user mentions international SEO, language tags, x-default, or hreflang issues.
12- Use when auditing locale alternates across HTML, headers, or sitemap implementations.
13
14Validate existing hreflang implementations or generate correct hreflang tags
15for multi-language and multi-region sites. Supports HTML, HTTP header, and
16XML sitemap implementations.
17
18## Validation Checks
19
20### 1. Self-Referencing Tags
21- Every page must include an hreflang tag pointing to itself
22- The self-referencing URL must exactly match the page's canonical URL
23- Missing self-referencing tags cause Google to ignore the entire hreflang set
24
25### 2. Return Tags
26- If page A links to page B with hreflang, page B must link back to page A
27- Every hreflang relationship must be bidirectional (A→B and B→A)
28- Missing return tags invalidate the hreflang signal for both pages
29- Check all language versions reference each other (full mesh)
30
31### 3. x-default Tag
32- Required: designates the fallback page for unmatched languages/regions
33- Typically points to the language selector page or English version
34- Only one x-default per set of alternates
35- Must also have return tags from all other language versions
36
37### 4. Language Code Validation
38- Must use ISO 639-1 two-letter codes (e.g., `en`, `fr`, `de`, `ja`)
39- Common errors:
40 - `eng` instead of `en` (ISO 639-2, not valid for hreflang)
41 - `jp` instead of `ja` (incorrect code for Japanese)
42 - `zh` without region qualifier (ambiguous; use `zh-Hans` or `zh-Hant`)
43
44### 5. Region Code Validation
45- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g., `en-US`, `en-GB`, `pt-BR`)
46- Format: `language-REGION` (lowercase language, uppercase region)
47- Common errors:
48 - `en-uk` instead of `en-GB` (UK is not a valid ISO 3166-1 code)
49 - `es-LA` (Latin America is not a country; use specific countries)
50 - Region without language prefix
51
52### 6. Canonical URL Alignment
53- Hreflang tags must only appear on canonical URLs
54- If a page has `rel=canonical` pointing elsewhere, hreflang on that page is ignored
55- The canonical URL and hreflang URL must match exactly (including trailing slashes)
56- Non-canonical pages should not be in any hreflang set
57
58### 7. Protocol Consistency
59- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)
60- Mixed HTTP/HTTPS in hreflang sets causes validation failures
61- After HTTPS migration, update all hreflang tags to HTTPS
62
63### 8. Cross-Domain Support
64- Hreflang works across different domains (e.g., example.com and example.de)
65- Cross-domain hreflang requires return tags on both domains
66- Verify both domains are verified in Google Search Console
67- Sitemap-based implementation recommended for cross-domain setups
68
69## Common Mistakes
70
71| Issue | Severity | Fix |
72|-------|----------|-----|
73| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL |
74| Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates |
75| Missing x-default | High | Add x-default pointing to fallback/selector page |
76| Invalid language code (e.g., `eng`) | High | Use ISO 639-1 two-letter codes |
77| Invalid region code (e.g., `en-uk`) | High | Use ISO 3166-1 Alpha-2 codes |
78| Hreflang on non-canonical URL | High | Move hreflang to canonical URL only |
79| HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS |
80| Trailing slash inconsistency | Medium | Match canonical URL format exactly |
81| Hreflang in both HTML and sitemap | Low | Choose one method (sitemap preferred for large sites) |
82| Language without region when needed | Low | Add region qualifier for geo-targeted content |
83
84## Implementation Methods
85
86### Method 1: HTML Link Tags
87Best for: Sites with <50 language/region variants per page.
88
89```html
90<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
91<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" />
92<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
93<link rel="alternate" hreflang="x-default" href="https://example.com/page" />
94```
95
96Place in `<head>` section. Every page must include all alternates including itself.
97
98### Method 2: HTTP Headers
99Best for: Non-HTML files (PDFs, documents).
100
101```
102Link: <https://example.com/page>; rel="alternate"; hreflang="en-US",
103 <https://example.com/fr/page>; rel="alternate"; hreflang="fr",
104 <https://example.com/page>; rel="alternate"; hreflang="x-default"
105```
106
107Set via server configuration or CDN rules.
108
109### Method 3: XML Sitemap (Recommended for large sites)
110Best for: Sites with many language variants, cross-domain setups, or 50+ pages.
111
112See Hreflang Sitemap Generation section below.
113
114### Method Comparison
115| Method | Best For | Pros | Cons |
116|--------|----------|------|------|
117| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats `<head>`, hard to maintain at scale |
118| HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML |
119| XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance |
120
121## Hreflang Generation
122
123### Process
1241. **Detect languages**: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
1252. **Map page equivalents**: Match corresponding pages across languages/regions
1263. **Validate language codes**: Verify all codes against ISO 639-1 and ISO 3166-1
1274. **Generate tags**: Create hreflang tags for each page including self-referencing
1285. **Verify return tags**: Confirm all relationships are bidirectional
1296. **Add x-default**: Set fallback for each page set
1307. **Output**: Generate implementation code (HTML, HTTP headers, or sitemap XML)
131
132## Hreflang Sitemap Generation
133
134### Sitemap with Hreflang
135```xml
136<?xml version="1.0" encoding="UTF-8"?>
137<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
138 xmlns:xhtml="http://www.w3.org/1999/xhtml">
139 <url>
140 <loc>https://example.com/page</loc>
141 <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
142 <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
143 <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
144 <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
145 </url>
146 <url>
147 <loc>https://example.com/fr/page</loc>
148 <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
149 <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
150 <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
151 <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
152 </url>
153</urlset>
154```
155
156Key rules:
157- Include the `xmlns:xhtml` namespace declaration
158- Every `<url>` entry must include ALL language alternates (including itself)
159- Each alternate must appear as a separate `<url>` entry with its own full set
160- Split at 50,000 URLs per sitemap file
161
162## Output
163
164### Hreflang Validation Report
165
166#### Summary
167- Total pages scanned: XX
168- Language variants detected: XX
169- Issues found: XX (Critical: X, High: X, Medium: X, Low: X)
170
171#### Validation Results
172| Language | URL | Self-Ref | Return Tags | x-default | Status |
173|----------|-----|----------|-------------|-----------|--------|
174| en-US | https://... | ✅ | ✅ | ✅ | ✅ |
175| fr | https://... | ❌ | ⚠️ | ✅ | ❌ |
176| de | https://... | ✅ | ❌ | ✅ | ❌ |
177
178### Generated Hreflang Tags
179- HTML `<link>` tags (if HTML method chosen)
180- HTTP header values (if header method chosen)
181- `hreflang-sitemap.xml` (if sitemap method chosen)
182
183### Recommendations
184- Missing implementations to add
185- Incorrect codes to fix
186- Method migration suggestions (e.g., HTML to sitemap for scale)
187
188## Error Handling
189
190| Scenario | Action |
191|----------|--------|
192| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. |
193| No hreflang tags found | Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. |
194| Invalid language/region codes detected | List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. |
195
196## Limitations
197- Use this skill only when the task clearly matches the scope described above.
198- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
199- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
200
201---
202
203**Source:** [`sickn33/agentic-awesome-skills`](https://github.com/sickn33/agentic-awesome-skills) → `skills/seo-hreflang/SKILL.md`
204
205**Also appears in:** `sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills/skills/seo-hreflang/SKILL.md`, `sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills-claude/skills/seo-hreflang/SKILL.md`, `sickn33/agentic-awesome-skills/plugins/agentic-bundle-aas-localization-international-growth/skills/seo-hreflang/SKILL.md`
thedixitjain