Hreflang Cluster Validator
Validate reciprocal hreflang clusters, ISO language-region codes, x-default usage, and canonical consistency across multilingual pages.
Live URL fetching uses a serverless layer to parse HTML hreflang and canonical tags. HTML paste and sitemap modes run entirely in your browser. No page content is stored.
Live URL fetching uses a serverless layer to fetch and parse HTML hreflang and canonical tags — only URL paths are transmitted, not page content beyond the HTML head. HTML paste and sitemap XML modes run entirely in your browser. No fetched HTML or page content is stored.
Overview
Hreflang is one of the most technically demanding international SEO signals to implement correctly at scale. A single tag tells search engines very little on its own — the entire cluster of language and region variants must be internally consistent, with every page referencing every other page in the set, including itself. A missing return tag anywhere in the chain can cause search engines to discard the entire cluster's hreflang annotations, silently sending users to the wrong locale without any obvious error in Search Console.
The most common failure mode is not a missing tag on one page — it is a broken reciprocal relationship between pages. Page A points to Page B with hreflang="fr", but Page B does not include a corresponding tag pointing back to Page A. This one-way reference is treated as invalid. The second most common failure is incorrect ISO codes — using en-UK instead of en-GB, or underscores instead of hyphens like en_US.
Validating a single page in isolation misses most of these issues. Cluster-level validation — checking every page against every other page in the set — is the only reliable way to surface missing return tags, inconsistent cluster sizes, x-default absence, and canonical-hreflang conflicts that undermine the implementation.
Use cases
When to use it
- Checking return-tag reciprocity across a multilingual clusterthe reciprocity matrix visualizes which page pairs have valid bidirectional hreflang references and highlights missing return tags per pair.
- Validating ISO language and region codesthe ISO checker flags invalid codes, underscore separators, the common en-UK mistake (correct: en-GB), and unknown language or region codes.
- Reviewing x-default usagecheck whether the cluster includes an x-default fallback and which URL it designates. Strongly recommended for clusters used as language selectors or with regions not explicitly listed.
- Spotting canonical-hreflang conflictswhen a localized page's canonical points to a different locale or outside the cluster, search engines may ignore its hreflang annotations. The tool flags these conflicts with actionable context.
- Comparing sitemap and HTML hreflang implementationsuse sitemap XML mode to parse xhtml:link hreflang entries and check cluster consistency within the sitemap independently of live HTML.
- Debugging Search Console localization issuesuse HTML paste mode for pages behind authentication or on staging environments where live fetch is not possible.
When it's not enough
- JavaScript-rendered hreflangthis tool parses static HTML returned by the server. Hreflang tags injected by JavaScript after page load are not visible to the parser and will not be detected in v1.
- Using hreflang as a ranking boosterhreflang is a localization signal that helps Google understand which variant to serve for which audience. It does not boost rankings directly and does not affect indexation of pages that have other problems.
- Skipping canonical self-referenceseach locale page should have a self-canonical as well as a self-referencing hreflang. Audit both — the tool checks self-referencing hreflang but canonical setup requires additional review.
How to use it
- 1
Choose input mode
Fetch URLs for live validation (serverless fetch of up to 30 pages). Paste HTML for staging or authenticated pages. Sitemap XML for sites using the sitemap implementation method.
- 2
Enter your cluster
For URL mode, paste one URL per line — ideally one per locale variant. For sitemap mode, paste or upload an XML sitemap containing xhtml:link hreflang entries.
- 3
Review the reciprocity matrix
The matrix is the most important output. Green cells show valid reciprocal pairs. Red cells show missing return tags — the most impactful hreflang error to fix.
- 4
Check ISO codes and x-default
Review flagged codes in the Summary tab. Look for en-UK (should be en-GB), underscore separators (should be hyphens), and x-default absence.
- 5
Fix and re-test
Add missing return tags, correct ISO codes, self-canonicalize locale pages, and ensure all hreflang href values use fully qualified absolute URLs. Re-run the validator after fixing.
Common errors and fixes
Missing return tag (No Return Tag error)
Page A has hreflang pointing to Page B, but Page B does not include a reciprocal hreflang pointing back to Page A. Add the missing return tag to Page B. Every page in the cluster must reference every other page in the set.
Page does not include itself in the hreflang set
Each page must include a self-referencing hreflang tag pointing to its own canonical URL using its own language-region code. Without the self-reference, the page's hreflang implementation is incomplete.
Invalid ISO code (e.g. en-UK, en_US)
Use en-GB for United Kingdom English (UK is not a valid ISO 3166-1 alpha-2 code — GB is). Use hyphens, not underscores: en-US not en_US. Use ISO 639-1 two-letter language codes and ISO 3166-1 alpha-2 region codes.
Relative or protocol-relative hreflang URLs
hreflang href attributes must use absolute URLs including the full protocol: https://example.com/fr/. Relative paths (/fr/) and protocol-relative URLs (//example.com/fr/) are not valid hreflang targets.
Canonical points outside the hreflang cluster
If a localized page's canonical points to a different locale page or a URL outside the cluster, search engines may ignore the hreflang annotations for that page. Each locale page should self-canonicalize to its own URL.
x-default missing
x-default designates a fallback URL for users from regions or languages not explicitly covered by the cluster. While not mandatory for every implementation, it is strongly recommended for sites with a language selector or homepage, and for clusters that do not cover all possible locales.
Inconsistent cluster size across pages
All pages in a cluster should reference the same set of language/region variants. If some pages list 3 hreflang entries and others list 5, the cluster is inconsistent. Standardize the full set across every page.
Frequently asked questions
Related
What is the "No Return Tag" error in hreflang?
A "No Return Tag" error means one page points to another with a rel="alternate" hreflang tag, but the target page does not include a reciprocal tag pointing back. Hreflang relationships are expected to be bidirectional — if the English page references the French page, the French page must also reference the English page.
When return tags are missing, search engines may choose to ignore the hreflang annotations for the affected pair entirely. The fix is to ensure every page in the cluster includes the full set of hreflang tags for all variants — including itself, and including a return reference back to any page that points to it.
Note that Google can still process bidirectionally consistent subsets of a cluster even if some language variants are omitted. If your French and German pages correctly reference each other but both omit Spanish, the French-German pair may still work. However, maintaining a complete and consistent set across all variants is the correct implementation and avoids ambiguity.
Hreflang ISO code cheat sheet
| Component | Expected format | Valid example | Common mistake |
|---|---|---|---|
| Language code | ISO 639-1 two-letter, lowercase | en, fr, de, zh, pt | ENG, english, English |
| Region code | ISO 3166-1 alpha-2, uppercase | GB, US, DE, FR, AU | UK (not valid — use GB), uk, United Kingdom |
| Language-region | lang-REGION (hyphen separator) | en-GB, zh-TW, pt-BR | en_GB, en-UK, en-gb, EN-GB |
| x-default | Literal string, lowercase | x-default | X-default, x_default, default |
The en-UK mistake is extremely common — the correct ISO 3166-1 alpha-2 code for the United Kingdom is GB, not UK. Use en-GB.
Example: clean 3-language hreflang cluster
Every page in the cluster must include the complete set of hreflang tags, including a reference to itself and the x-default fallback.
<!-- On EVERY page in the cluster --> <link rel="alternate" hreflang="en" href="https://example.com/en/" /> <link rel="alternate" hreflang="fr" href="https://example.com/fr/" /> <link rel="alternate" hreflang="de" href="https://example.com/de/" /> <link rel="alternate" hreflang="x-default" href="https://example.com/en/" />
- Each page includes all variants — not just a reference to itself.
- All URLs are fully qualified (absolute, including protocol).
- The same cluster set appears on every locale page — consistency is required.
- x-default designates the fallback for unmatched locales.