Hreflang reciprocity repair

Hreflang is ignored unless every version points back at every other version, including itself. Most broken implementations look correct on the page you inspect - the failure is on the sibling you did not check. This skill finds the one-way edges.

The skill file

---
name: hreflang-reciprocity-repair
description: Use when translated pages exist and are indexed but never surface for the right country, or when Search Console reports "no return tags" against your alternates.
---

# Hreflang reciprocity repair

Hreflang is ignored unless every version points back at every other version, including itself. Most broken implementations look correct on the page you inspect - the failure is on the sibling you did not check. This skill finds the one-way edges.

## What you need first

- A crawl exporting every hreflang annotation per URL
- The canonical declared on each of those URLs

## Method

1. Build a directed graph: for every URL, an edge to each alternate it declares.
2. A cluster is valid only when it is fully connected in both directions AND every member declares itself. Find clusters that are not.
3. The most common defect is a missing self-reference. A page listing fr, de and es but not its own en is a broken cluster even though nothing looks wrong on that page.
4. Cross-check hreflang against canonical. If a page canonicalises to a different URL than the one its siblings name as its alternate, the whole cluster is discarded - this is the failure that survives every visual inspection.
5. Verify each alternate returns 200 directly. An alternate pointing at a URL that redirects is dropped silently, which is why alternates must use the exact canonical form including trailing-slash convention.
6. Confirm x-default exists once per cluster and points at the version you serve to unmatched visitors, not simply at the English page by reflex.
7. Re-crawl and confirm every cluster is now bidirectional and self-referencing.

## What this produces

A list of broken clusters with the specific missing edge in each, and the canonical conflicts that would have invalidated them anyway.

## Where this goes wrong

- Adding hreflang to the head of every page but never checking the reverse direction from the siblings
- Alternates pointing at redirecting URLs - correct-looking markup that is discarded before it is read
- Letting a session-based locale redirect override the URL, so a crawler requesting the English alternate is served another language and the cluster never validates

---

From the QuQi skill library - https://www.quqi.io/skills/hreflang-reciprocity-repair

What you need first

• A crawl exporting every hreflang annotation per URL
• The canonical declared on each of those URLs

Method

1. 01 Build a directed graph: for every URL, an edge to each alternate it declares.
2. 02 A cluster is valid only when it is fully connected in both directions AND every member declares itself. Find clusters that are not.
3. 03 The most common defect is a missing self-reference. A page listing fr, de and es but not its own en is a broken cluster even though nothing looks wrong on that page.
4. 04 Cross-check hreflang against canonical. If a page canonicalises to a different URL than the one its siblings name as its alternate, the whole cluster is discarded - this is the failure that survives every visual inspection.
5. 05 Verify each alternate returns 200 directly. An alternate pointing at a URL that redirects is dropped silently, which is why alternates must use the exact canonical form including trailing-slash convention.
6. 06 Confirm x-default exists once per cluster and points at the version you serve to unmatched visitors, not simply at the English page by reflex.
7. 07 Re-crawl and confirm every cluster is now bidirectional and self-referencing.

What this produces

A list of broken clusters with the specific missing edge in each, and the canonical conflicts that would have invalidated them anyway.

Where this goes wrong

• Adding hreflang to the head of every page but never checking the reverse direction from the siblings
• Alternates pointing at redirecting URLs - correct-looking markup that is discarded before it is read
• Letting a session-based locale redirect override the URL, so a crawler requesting the English alternate is served another language and the cluster never validates

More in International SEO