/seo-hreflang

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

Hreflang & International SEO

Shared Data Cache

**Step 0 -- Check shared data cache:**

Before gathering, check `.seo-cache/` for reusable context from related SEO skills. Reference: `../seo/references/shared-data-cache.md` for schemas and dependency map.

Check these cache files when present:

• `.seo-cache/site-meta.json` for domain, business type, industry, and crawl context
• `.seo-cache/audit-scores.json` for prior full-audit priorities
• `.seo-cache/pages/{url-slug}/page-analysis.json` for page-level context when a URL is provided

• If found: parse and use clearly valid fields (note "Using cached [X] from [date]")
• If missing, corrupt, or irrelevant: continue with fresh evidence
• If the user says "refresh" or "re-run": ignore cache reads and overwrite on write

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