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

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, Turkiye) Google documents Search experiences that exist only in certain countries: aggregator units , supplier units , and carousels for hotel, flight, long distance transport, and product queries shown to users in the EEA, South Africa, and Turkiye (documentation added 2026 09 08). 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. Place in <head section. Every page must include all alternates including itself. Method 2: HTTP Headers Best for: Non HTML files (PDFs, documents). 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 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 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.

seo-hreflang