Sign in Start free

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.

CATEGORY
International SEO
FORMAT
hreflang-reciprocity-repair.md
STEPS
7
PRICE
Free - no account
WHEN TO REACH FOR THIS

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.

The skill file

hreflang-reciprocity-repair.md 
---
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
Free to download · no account, no email

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

Use this skill in your own AI

The download is a plain markdown file with the name and trigger in its frontmatter. Where an assistant supports skills it can load itself, that frontmatter is what it reads to decide this one applies.

Claude Code Save it as ~/.claude/skills/hreflang-reciprocity-repair/SKILL.md and Claude loads it on its own when what you are doing matches the trigger line. Put it in .claude/skills inside a project instead if the whole team should have it.
Claude Upload the file in the skills section of your settings. Once it is there it applies itself in any conversation where the trigger fits, so you do not have to remember it exists.
ChatGPT There is no skills format to install into, so paste the file contents into a Project instruction or a Custom GPT instead. It then applies to every chat in that project rather than only the one you paste it into.
Anything else Paste the markdown into the chat before your question. It works in any assistant, it just has to be pasted again each time.

Questions about this skill

When is graph-checking reciprocity the right move rather than re-reading the tags on the page that is failing?

The page you inspect is almost always fine; the missing edge sits on a sibling you never opened. Reading tags page by page cannot show a one-way relationship, because each side looks correct in isolation. Build the directed graph when translated pages are indexed but never surface in their market, or when Search Console reports no return tags.

What do I need in hand before starting?

A crawl exporting every hreflang annotation per URL, and the canonical each of those URLs declares. Without the canonicals you will repair the graph and the clusters will still be discarded, because a page canonicalising away from the URL its siblings name as its alternate invalidates the set regardless of how complete the annotations are.

What do I end up with, and which part of it gets used?

A list of broken clusters naming the specific missing edge in each, alongside the canonical conflicts. The edge list is what a developer works from, but read the conflicts first: fixing edges inside a cluster that also has a canonical mismatch changes nothing, so those rows have to be resolved before the rest is worth shipping.

What ruins this most often?

Declaring alternates that redirect. Markup naming a non-canonical form, wrong trailing slash, http, an old path, is dropped silently, so the cluster reads as broken while every page looks correct. Worse is a session-based locale redirect serving another language at the alternate URL, which means the crawler never validates the set however many times you reissue the tags.

More in International SEO

Locale redirect trap audit

Use when visitors report being unable to switch back to a language, or when a shared link opens...

Translation key drift guard

Use on any site whose translation keys are the English source text, where editing a headline sil...

RTL layout audit

Use before shipping Arabic, Hebrew, Farsi or Urdu, or when an RTL locale shows overlapping text,...

Multilingual sitemap coverage

Use when translated pages exist and are linked but receive no impressions, and the sitemap lists...