---

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". user-invocable: true argument-hint: "[url]" license: MIT metadata: author: AgriciDaniel version: "2.4.0" category: seo

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.

5c. Region-specific Search units (EEA, South Africa, Türkiye)

• Google documents Search experiences that exist only in certain regions (documentation added 2026-09-08; https://developers.google.com/search/docs/appearance/aggregator-features):
  • EEA only: aggregator units and supplier units (hotels, flights, ground transportation, products, and since 2026-09-18 local businesses), the ecosystem carousel, and job-site features.
  • Türkiye: places-site features (hotels, local businesses).
  • South Africa: a badge and refinement chip for travel, products, car hire, food delivery and ground transportation.
  • Structured data carousels in all three, with different query types. Eligibility and participation are documented per unit; they are not ranking signals.
• When a site serves those regions with hreflang variants, note in the report whether the business is an aggregator or a direct supplier and point to the regional documentation, so the client is not surprised by a different result layout in those markets.

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

1. Detect languages: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
2. Map page equivalents: Match corresponding pages across languages/regions
3. Validate language codes: Verify all codes against ISO 639-1 and ISO 3166-1
4. Generate tags: Create hreflang tags for each page including self-referencing
5. Verify return tags: Confirm all relationships are bidirectional
6. Add x-default: Set fallback for each page set
7. 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:

1. Identify all language versions and their target markets
2. Load the relevant cultural profile(s)
3. Check CTAs match cultural expectations (direct vs indirect)
4. Check trust signals are locale-appropriate (certifications, legal pages)
5. Check for foreign brand references on localized pages
6. Check number/date/currency formatting consistency
7. 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