Validate existing hreflang implementations or generate correct hreflang tags for multi-language and multi-region sites. Supports HTML link tags, HTTP headers, and XML sitemap methods. Detects 10+ common mistakes that cause Google to ignore your international targeting.
When you run /seo hreflang, Claude SEO scans your site for hreflang implementations across all three standard methods: HTML link tags, HTTP headers, and XML sitemaps. It validates every tag against 8 critical checks and flags issues by severity.
The tool detects language indicators from URL paths, subdomains, TLDs, and HTML lang attributes. It maps equivalent pages across languages, validates ISO 639-1 language codes and ISO 3166-1 region codes, and verifies that every hreflang relationship is bidirectional.
What each validation check covers
The hreflang audit runs 8 checks across your entire site. Missing self-referencing tags and missing return tags are the two most common mistakes, and both cause Google to ignore the entire hreflang set for affected pages.
01
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.
02
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. Missing return tags invalidate the signal for both pages.
03
X-DEFAULT TAG
Designates the fallback page for unmatched languages or regions. Typically points to the language selector page or English version. Only one x-default per set of alternates.
04
LANGUAGE CODES
Must use ISO 639-1 two-letter codes. Detects common errors like "eng" instead of "en", "jp" instead of "ja", and "zh" without a region qualifier for Chinese variants.
05
REGION CODES
Optional region qualifier uses ISO 3166-1 Alpha-2 format. Catches errors like "en-uk" (should be "en-GB"), "es-LA" (Latin America is not a country), and missing language prefixes.
06
CANONICAL ALIGNMENT
Hreflang tags must only appear on canonical URLs. If a page has rel=canonical pointing elsewhere, hreflang on that page is ignored. URLs must match exactly, including trailing slashes.
07
PROTOCOL CONSISTENCY
All URLs in an hreflang set must use the same protocol. Mixed HTTP and HTTPS in hreflang sets causes validation failures. Flags sites that need post-migration updates.
08
CROSS-DOMAIN SUPPORT
Validates hreflang across different domains, for example example.com and example.de. Checks return tags on both domains and recommends sitemap-based implementation for cross-domain setups.
GENERATOR
TAG GENERATION
Generates complete hreflang tag sets in your preferred format: HTML link tags, HTTP Link headers, or XML sitemap with xhtml:link namespace. Includes self-referencing and x-default tags automatically.
// COMMON MISTAKES
10 HREFLANG ERRORS DETECTED
These are the most common hreflang implementation mistakes. Claude SEO flags each one with a severity level and provides the exact fix needed.
Issue
Severity
Fix
Missing self-referencing tag
Critical
Add hreflang pointing to same page URL
Missing return tags (A to B but no B to A)
Critical
Add matching return tags on all alternates
Missing x-default
High
Add x-default pointing to fallback 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)
Claude SEO scans your site for all hreflang implementations, validates every tag against 8 checks, and generates a validation report with corrected tags ready to implement.
Generation process
When generating hreflang tags for a new implementation, the tool follows this process:
Detect languages - scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
Map page equivalents - match corresponding pages across languages and 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
Claude SEO detects 10 common hreflang issues: missing self-referencing tags, missing return tags (bidirectional validation), missing x-default, invalid ISO 639-1 language codes (like "eng" instead of "en"), invalid ISO 3166-1 region codes (like "en-uk" instead of "en-GB"), hreflang on non-canonical URLs, HTTP/HTTPS protocol mismatch, trailing slash inconsistency, duplicate implementation methods, and missing region qualifiers.
Claude SEO validates and generates hreflang in all three standard methods: HTML link tags in the head section (best for sites with fewer than 50 language variants per page), HTTP Link headers (best for non-HTML files like PDFs), and XML sitemap with xhtml:link namespace (recommended for large sites and cross-domain setups).
Yes. Claude SEO can scan your site, detect language indicators from URL paths, subdomains, TLDs, and HTML lang attributes, then map equivalent pages across languages. It generates complete hreflang tag sets including self-referencing tags and x-default in your preferred format: HTML, HTTP headers, or XML sitemap.
Yes. Hreflang supports cross-domain setups, for example example.com and example.de. Claude SEO validates cross-domain hreflang by checking return tags on both domains. For cross-domain implementations, the sitemap method is recommended. Both domains should be verified in Google Search Console.
Yes. Claude SEO is fully open-source under the MIT license. The hreflang audit runs entirely through Claude Code with no external API costs. No paid tiers, no freemium.
// RELATED SKILLS
EXPLORE MORE
TECHNICAL SEO
Deep technical analysis across 9 categories including crawlability, indexability, security, and Core Web Vitals.
