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
- Recommended when a selector/fallback URL exists: 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)
- An optional ISO 15924 script subtag is the documented, official mechanism
for script:
zh-Hant (Traditional) / zh-Hans (Simplified). Script may
combine with a region, e.g. zh-Hans-US is valid (language + script + region).
- Common errors:
eng instead of en (ISO 639-2, not valid for hreflang)
jp instead of ja (incorrect code for Japanese)
zh is valid but ambiguous for script-specific pages; prefer zh-Hans or zh-Hant when targeting a script
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)
- A country code alone is invalid, you cannot specify a region without a
language (Google's own bad example is
be, which is actually the Belarusian
language code, not Belgium).
- Common errors:
en-uk instead of en-GB (UK is not a valid ISO 3166-1 region code)
EU / UN as a region (not valid ISO 3166-1 values)
es-LA (Latin America is not a country; use specific countries)
- Region without language prefix
5b. Geo-targeting signal hierarchy
- Practical locale-signal heuristic: ccTLD > hreflang annotations >
server location/IP > addresses/language/currency/Business Profile. Do not
present this as a confirmed Google ranking order. hreflang is a
hint, not a directive. Google ignores locational meta tags and
HTML geotargeting attributes.
- The Search Console International Targeting report and the manual
country-targeting setting were removed in 2022, do not recommend setting
country targeting in GSC; hreflang is the remaining lever.
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
- Use Google Search Console verification for monitoring or cross-site sitemap submission when needed
- 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 when fallback behavior is required |
Medium |
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 whichever comes first: 50,000 URLs or 50MB uncompressed 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)
Cultural Adaptation Assessment
When analyzing a multi-language site, go beyond technical hreflang validation to assess
whether the content is culturally adapted for each target market.
Load references/cultural-profiles.md for pre-built profiles (DACH, Francophone, Hispanic, Japanese).
Assessment steps:
- Identify all language versions and their target markets
- Load the relevant cultural profile(s)
- Check CTAs match cultural expectations (direct vs indirect)
- Check trust signals are locale-appropriate (certifications, legal pages)
- Check for foreign brand references on localized pages
- Check number/date/currency formatting consistency
- Flag cultural adaptation issues as Medium severity
Output: Cultural Adaptation Score per language version (0-100) with specific findings.
Content Parity Audit
Command: /seo hreflang audit <directory-or-url>
Audit content parity across all language versions of a site or local content directory.
Load references/content-parity.md for the full parity matrix and scoring methodology.
What it checks:
- Page existence across all declared languages
- Section structure equivalence (H2/H3 count)
- SEO element parity (title, meta, schema localization)
- Word count ratio validation (DE should be 25-35% longer than EN, JA 10-25% shorter)
- Freshness tracking (stale translations detected via timestamps)
- Cultural marker scanning (foreign brands, wrong legal references, untranslated elements)
Output: Parity matrix table with per-page scores and prioritized action items.
Locale Format Validation
Load references/locale-formats.md for number, date, currency, address, and phone format
reference tables per locale.
Checks:
- Number format consistency (e.g., "1,000.00" should be "1.000,00" on de-DE pages)
- Date format matches locale expectations
- Currency symbols and placement correct for target market
- Phone numbers use international format with correct country code
Reference Files
Load on-demand as needed (do NOT load all at startup):
references/cultural-profiles.md: DACH, Francophone, Hispanic, Japanese cultural adaptation profiles
references/locale-formats.md: Number, date, currency, address, phone format tables per locale
references/content-parity.md: Content parity audit methodology and scoring
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. |
| Cultural profile not available for language |
Use the Default Profile checklist from cultural-profiles.md. Note that assessment is based on general guidelines, not a pre-built profile. |
| Content parity directory empty |
Report that no content files were found. Suggest verifying the directory path or providing a URL for live site analysis. |
1---
2name: seo-hreflang
3description: >
4 Hreflang and international SEO audit, validation, and generation. Detects
5 common mistakes, validates language/region codes, and generates correct
6 hreflang implementations. Use when user says "hreflang", "i18n SEO",
7 "international SEO", "multi-language", "multi-region", or "language tags".
8user-invocable: true
9argument-hint: "[url]"
10license: MIT
11metadata:
12 source: https://skillmd.com/skills/gabrielmoreira/seo-hreflang
13 author: AgriciDaniel
14 version: "2.2.5"
15 category: seo
16---
17
18# Hreflang & International SEO
19
20Validate existing hreflang implementations or generate correct hreflang tags
21for multi-language and multi-region sites. Supports HTML, HTTP header, and
22XML sitemap implementations.
23
24## Validation Checks
25
26### 1. Self-Referencing Tags
27- Every page must include an hreflang tag pointing to itself
28- The self-referencing URL must exactly match the page's canonical URL
29- Missing self-referencing tags cause Google to ignore the entire hreflang set
30
31### 2. Return Tags
32- If page A links to page B with hreflang, page B must link back to page A
33- Every hreflang relationship must be bidirectional (A→B and B→A)
34- Missing return tags invalidate the hreflang signal for both pages
35- Check all language versions reference each other (full mesh)
36
37### 3. x-default Tag
38- Recommended when a selector/fallback URL exists: designates the fallback page for unmatched languages/regions
39- Typically points to the language selector page or English version
40- Only one x-default per set of alternates
41- Must also have return tags from all other language versions
42
43### 4. Language Code Validation
44- Must use ISO 639-1 two-letter codes (e.g., `en`, `fr`, `de`, `ja`)
45- An **optional ISO 15924 script subtag** is the documented, official mechanism
46 for script: `zh-Hant` (Traditional) / `zh-Hans` (Simplified). Script may
47 combine with a region, e.g. `zh-Hans-US` is valid (language + script + region).
48- Common errors:
49 - `eng` instead of `en` (ISO 639-2, not valid for hreflang)
50 - `jp` instead of `ja` (incorrect code for Japanese)
51 - `zh` is valid but ambiguous for script-specific pages; prefer `zh-Hans` or `zh-Hant` when targeting a script
52
53### 5. Region Code Validation
54- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g., `en-US`, `en-GB`, `pt-BR`)
55- Format: `language-REGION` (lowercase language, uppercase region)
56- A **country code alone is invalid**, you cannot specify a region without a
57 language (Google's own bad example is `be`, which is actually the Belarusian
58 *language* code, not Belgium).
59- Common errors:
60 - `en-uk` instead of `en-GB` (UK is not a valid ISO 3166-1 region code)
61 - `EU` / `UN` as a region (not valid ISO 3166-1 values)
62 - `es-LA` (Latin America is not a country; use specific countries)
63 - Region without language prefix
64
65### 5b. Geo-targeting signal hierarchy
66- Practical locale-signal heuristic: **ccTLD > hreflang annotations >
67 server location/IP > addresses/language/currency/Business Profile**. Do not
68 present this as a confirmed Google ranking order. hreflang is a
69 **hint, not a directive**. Google **ignores** locational meta tags and
70 HTML geotargeting attributes.
71- The Search Console **International Targeting report and the manual
72 country-targeting setting were removed in 2022**, do **not** recommend setting
73 country targeting in GSC; hreflang is the remaining lever.
74
75### 6. Canonical URL Alignment
76- Hreflang tags must only appear on canonical URLs
77- If a page has `rel=canonical` pointing elsewhere, hreflang on that page is ignored
78- The canonical URL and hreflang URL must match exactly (including trailing slashes)
79- Non-canonical pages should not be in any hreflang set
80
81### 7. Protocol Consistency
82- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)
83- Mixed HTTP/HTTPS in hreflang sets causes validation failures
84- After HTTPS migration, update all hreflang tags to HTTPS
85
86### 8. Cross-Domain Support
87- Hreflang works across different domains (e.g., example.com and example.de)
88- Cross-domain hreflang requires return tags on both domains
89- Use Google Search Console verification for monitoring or cross-site sitemap submission when needed
90- Sitemap-based implementation recommended for cross-domain setups
91
92## Common Mistakes
93
94| Issue | Severity | Fix |
95|-------|----------|-----|
96| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL |
97| Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates |
98| Missing x-default when fallback behavior is required | Medium | Add x-default pointing to fallback/selector page |
99| Invalid language code (e.g., `eng`) | High | Use ISO 639-1 two-letter codes |
100| Invalid region code (e.g., `en-uk`) | High | Use ISO 3166-1 Alpha-2 codes |
101| Hreflang on non-canonical URL | High | Move hreflang to canonical URL only |
102| HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS |
103| Trailing slash inconsistency | Medium | Match canonical URL format exactly |
104| Hreflang in both HTML and sitemap | Low | Choose one method (sitemap preferred for large sites) |
105| Language without region when needed | Low | Add region qualifier for geo-targeted content |
106
107## Implementation Methods
108
109### Method 1: HTML Link Tags
110Best for: Sites with <50 language/region variants per page.
111
112```html
113<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
114<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" />
115<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
116<link rel="alternate" hreflang="x-default" href="https://example.com/page" />
117```
118
119Place in `<head>` section. Every page must include all alternates including itself.
120
121### Method 2: HTTP Headers
122Best for: Non-HTML files (PDFs, documents).
123
124```
125Link: <https://example.com/page>; rel="alternate"; hreflang="en-US",
126 <https://example.com/fr/page>; rel="alternate"; hreflang="fr",
127 <https://example.com/page>; rel="alternate"; hreflang="x-default"
128```
129
130Set via server configuration or CDN rules.
131
132### Method 3: XML Sitemap (Recommended for large sites)
133Best for: Sites with many language variants, cross-domain setups, or 50+ pages.
134
135See Hreflang Sitemap Generation section below.
136
137### Method Comparison
138| Method | Best For | Pros | Cons |
139|--------|----------|------|------|
140| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats `<head>`, hard to maintain at scale |
141| HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML |
142| XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance |
143
144## Hreflang Generation
145
146### Process
1471. **Detect languages**: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
1482. **Map page equivalents**: Match corresponding pages across languages/regions
1493. **Validate language codes**: Verify all codes against ISO 639-1 and ISO 3166-1
1504. **Generate tags**: Create hreflang tags for each page including self-referencing
1515. **Verify return tags**: Confirm all relationships are bidirectional
1526. **Add x-default**: Set fallback for each page set
1537. **Output**: Generate implementation code (HTML, HTTP headers, or sitemap XML)
154
155## Hreflang Sitemap Generation
156
157### Sitemap with Hreflang
158```xml
159<?xml version="1.0" encoding="UTF-8"?>
160<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
161 xmlns:xhtml="http://www.w3.org/1999/xhtml">
162 <url>
163 <loc>https://example.com/page</loc>
164 <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
165 <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
166 <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
167 <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
168 </url>
169 <url>
170 <loc>https://example.com/fr/page</loc>
171 <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
172 <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
173 <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
174 <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
175 </url>
176</urlset>
177```
178
179Key rules:
180- Include the `xmlns:xhtml` namespace declaration
181- Every `<url>` entry must include ALL language alternates (including itself)
182- Each alternate must appear as a separate `<url>` entry with its own full set
183- Split at whichever comes first: 50,000 URLs or 50MB uncompressed per sitemap file
184
185## Output
186
187### Hreflang Validation Report
188
189#### Summary
190- Total pages scanned: XX
191- Language variants detected: XX
192- Issues found: XX (Critical: X, High: X, Medium: X, Low: X)
193
194#### Validation Results
195| Language | URL | Self-Ref | Return Tags | x-default | Status |
196|----------|-----|----------|-------------|-----------|--------|
197| en-US | https://... | ✅ | ✅ | ✅ | ✅ |
198| fr | https://... | ❌ | ⚠️ | ✅ | ❌ |
199| de | https://... | ✅ | ❌ | ✅ | ❌ |
200
201### Generated Hreflang Tags
202- HTML `<link>` tags (if HTML method chosen)
203- HTTP header values (if header method chosen)
204- `hreflang-sitemap.xml` (if sitemap method chosen)
205
206### Recommendations
207- Missing implementations to add
208- Incorrect codes to fix
209- Method migration suggestions (e.g., HTML to sitemap for scale)
210
211## Cultural Adaptation Assessment
212
213When analyzing a multi-language site, go beyond technical hreflang validation to assess
214whether the content is culturally adapted for each target market.
215
216Load `references/cultural-profiles.md` for pre-built profiles (DACH, Francophone, Hispanic, Japanese).
217
218**Assessment steps:**
2191. Identify all language versions and their target markets
2202. Load the relevant cultural profile(s)
2213. Check CTAs match cultural expectations (direct vs indirect)
2224. Check trust signals are locale-appropriate (certifications, legal pages)
2235. Check for foreign brand references on localized pages
2246. Check number/date/currency formatting consistency
2257. Flag cultural adaptation issues as Medium severity
226
227**Output:** Cultural Adaptation Score per language version (0-100) with specific findings.
228
229## Content Parity Audit
230
231**Command:** `/seo hreflang audit <directory-or-url>`
232
233Audit content parity across all language versions of a site or local content directory.
234
235Load `references/content-parity.md` for the full parity matrix and scoring methodology.
236
237**What it checks:**
238- Page existence across all declared languages
239- Section structure equivalence (H2/H3 count)
240- SEO element parity (title, meta, schema localization)
241- Word count ratio validation (DE should be 25-35% longer than EN, JA 10-25% shorter)
242- Freshness tracking (stale translations detected via timestamps)
243- Cultural marker scanning (foreign brands, wrong legal references, untranslated elements)
244
245**Output:** Parity matrix table with per-page scores and prioritized action items.
246
247## Locale Format Validation
248
249Load `references/locale-formats.md` for number, date, currency, address, and phone format
250reference tables per locale.
251
252**Checks:**
253- Number format consistency (e.g., "1,000.00" should be "1.000,00" on de-DE pages)
254- Date format matches locale expectations
255- Currency symbols and placement correct for target market
256- Phone numbers use international format with correct country code
257
258## Reference Files
259
260Load on-demand as needed (do NOT load all at startup):
261- `references/cultural-profiles.md`: DACH, Francophone, Hispanic, Japanese cultural adaptation profiles
262- `references/locale-formats.md`: Number, date, currency, address, phone format tables per locale
263- `references/content-parity.md`: Content parity audit methodology and scoring
264
265## Error Handling
266
267| Scenario | Action |
268|----------|--------|
269| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. |
270| No hreflang tags found | Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. |
271| Invalid language/region codes detected | List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. |
272| Cultural profile not available for language | Use the Default Profile checklist from cultural-profiles.md. Note that assessment is based on general guidelines, not a pre-built profile. |
273| Content parity directory empty | Report that no content files were found. Suggest verifying the directory path or providing a URL for live site analysis. |