Hreflang & International 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

• 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

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

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 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

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 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