hreflang-cluster-check

---
name: hreflang-cluster-check
description: Validates hreflang and canonical clusters across a multilingual site. Use when the user asks why the wrong language ranks, reports hreflang errors in Search Console, or is launching a new locale.
---

# hreflang cluster check

## When to use this
The wrong language ranks, Search Console reports hreflang errors, or a new
locale is being launched.

## Procedure
1. Enumerate every locale and the URL pattern for each.
2. For one representative page, fetch **every** locale variant.
3. Check the four failure modes listed in [references/failure-modes.md](references/failure-modes.md).
4. Report per-URL, not per-site. "hreflang is broken" is not a finding.

## Rules
- Reciprocity is mandatory: if page A declares B, then B must declare A. A
  one-way declaration is ignored entirely by search engines.
- Every cluster needs exactly one `x-default`.
- Each locale variant must canonicalise to **itself**, never across locales.
  A cross-locale canonical removes the page from the index.
- Language codes must be valid BCP-47. `en-UK` is not a language code; `en-GB` is.

# The four hreflang failure modes

1. **Non-reciprocal** — A points at B, B does not point back. Search engines
   discard the whole relationship.
2. **Cross-locale canonical** — the Spanish page canonicalises to the English
   one, so the Spanish page never enters the index.
3. **Missing or duplicated x-default** — no fallback for unmatched locales, or
   two competing fallbacks.
4. **Invalid code** — a region used as a language, an underscore instead of a
   hyphen, or a non-existent subtag.