A hreflang audit is a check of language and regional annotations that helps search engines select the correct page version. Claude SEO validates existing implementations or generates tags for multilingual and multiregional sites across HTML, HTTP header, and XML sitemap methods.
Coverage is limited to retrieved resources, and source-level method heuristics still need current Google review.
OUTCOME
A hreflang diagnostic and tag draft across retrieved HTML, HTTP headers, and XML sitemaps.
REQUIRED INPUT
A reachable international page or site supplied to /seo hreflang <url>, with known locale intent when available.
READINESS
Blocked pages, authentication, crawl limits, and incomplete sitemap discovery reduce coverage. Equivalent pages need human confirmation.
LOCAL OUTPUT
A validation report and draft annotations using ISO 639-1, optional ISO 15924, optional region codes, and optional x-default.
SIDE EFFECTS
Fetches pages, headers, and sitemaps and may write local drafts. It does not implement tags or change production.
COST + APPROVAL
The base skill needs no paid SEO-data provider. Claude Code and network access can cost separately; implementation needs owner review.
// HOW IT WORKS
What does a hreflang audit validate?
When you run /seo hreflang, Claude SEO reviews the pages, HTTP headers, and XML sitemaps it can retrieve. It checks self-references, reciprocal links, code formats, canonical alignment, fully qualified URLs, and related implementation details. The report's coverage is limited to resources that were successfully fetched.
The tool proposes equivalents from URL paths, subdomains, TLDs, and HTML language attributes, but a person must confirm that the pages serve equivalent content. It validates ISO 639-1 language codes, optional ISO 15924 script subtags, optional ISO 3166-1 region codes, and reciprocal relationships.
What each validation check covers
The audit applies its review categories only to retrieved resources. The v2.2.5 source includes a transport-consistency rule and recommends sitemaps for some setups. Current Google guidance requires fully qualified alternate URLs and treats HTML, HTTP header, and sitemap methods as equivalent, so treat those source rules as operational review prompts rather than universal search requirements.
01
SELF-REFERENCING TAGS
Every alternate should list itself and the other versions. The self-reference should use the page's canonical URL. Missing entries can prevent the annotations from being processed as intended.
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
Optional fallback for unmatched languages or regions, often a selector page. The current generation process includes it, so remove or revise it when no real fallback exists.
04
LANGUAGE CODES
Uses ISO 639-1 language codes with optional ISO 15924 script subtags. "zh" is valid; use "zh-Hans" or "zh-Hant" when script targeting matters.
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
TRANSPORT REVIEW
The current skill flags mixed HTTP and HTTPS. Google instead requires complete canonical alternate URLs; mixed transport is a migration clue, not an error by itself.
08
CROSS-DOMAIN SUPPORT
Reviews reciprocal annotations across domains. The source recommends sitemaps here, but Google gives no search preference to sitemap over HTML for cross-domain use.
GENERATOR
TAG GENERATION
Drafts HTML link tags, HTTP Link headers, or XML sitemap annotations from retrieved evidence. The source process includes x-default, which needs fallback confirmation before use.
// COMMON MISTAKES
Which hreflang errors are 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 when a fallback exists
Review
Consider x-default for the selector or fallback URL
Invalid language code (e.g., eng)
High
Use ISO 639-1 with an optional ISO 15924 script subtag
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
Mixed transport (current skill check)
Review
Confirm every alternate is fully qualified and canonical; mixed transport is not itself a Google error
Trailing slash inconsistency
Medium
Match canonical URL format exactly
Hreflang in both HTML and sitemap
Info
Choose one method when duplicate maintenance creates risk; Google treats the methods as equivalent
Language without region when needed
Low
Add region qualifier for geo-targeted content
Implementation method comparison
Google treats all three methods as equivalent for Search. The current skill source recommends sitemaps for scale and cross-domain setups; treat that as a maintenance preference, not an expected ranking benefit.
Claude SEO reviews the hreflang implementations it can retrieve and drafts corrections. The report must state any pages, headers, or sitemaps it could not access, and a person should verify page equivalence and canonical URLs before implementation.
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 ISO 639-1 language, optional ISO 15924 script, and optional ISO 3166-1 region codes
Generate tags - create hreflang tags for each page including self-referencing
Verify return tags - confirm all relationships are bidirectional
Review x-default - the source process includes it; keep it only when a selector or fallback URL exists
On resources it retrieves, the v2.2.5 skill reviews self-references, reciprocal links, language and region codes, canonical alignment, formatting, x-default, and a source-defined transport-consistency rule. Google requires fully qualified canonical alternate URLs, but not one shared transport across every alternate. Treat mixed transport as a review clue, not a universal error. x-default is optional, and ISO 15924 script subtags such as zh-Hant and zh-Hans are valid.
Claude SEO can review and draft HTML link tags, HTTP Link headers, and XML sitemap annotations. Its source recommends sitemaps for scale and cross-domain setups, but Google treats all three methods as equivalent for Search and recommends the easiest method to implement and maintain. Treat the source recommendation as an operational preference, not a search advantage.
It can draft tags from the pages, headers, and sitemaps it successfully retrieves, using URL, subdomain, TLD, and HTML language evidence. A person must confirm equivalent pages and canonical URLs. The current generation process includes self-references, reciprocal links, and x-default; keep x-default only when a selector or fallback URL actually exists.
Yes. Hreflang can connect alternate pages across domains as long as each retrieved alternate uses reciprocal annotations. HTML, HTTP header, and sitemap methods remain equivalent. Search Console verification can help monitoring or sitemap submission, but it is not a validity requirement for cross-domain hreflang.
The Claude SEO code is open-source under the MIT license and the base hreflang skill does not require a paid SEO-data provider. Claude Code usage, network access, and any optional services can still have their own access requirements and costs.
// RELATED SKILLS
EXPLORE MORE
TECHNICAL SEO
Deep technical analysis across 9 categories including crawlability, indexability, security, and Core Web Vitals.
