A reproducible audit for return-tag reciprocity

A reproducible audit for return-tag reciprocity

Return-tag errors ("no return tags" in GSC) are the most common hreflang failure we see, yet most teams hunt them page-by-page. A faster, falsifiable method:

— Crawl all URLs that emit hreflang and dump every annotation to a flat table: source URL, target URL, language-region value.
— Build the reverse table by swapping source and target.
— Left-join the two. Any source→target pair with no matching target→source row is a broken reciprocal link. This isolates the exact missing edge, not just the offending page.

We ran this on a 4,200-URL retail set: 31% of pairs failed reciprocity, but 80% of failures traced to just three templates where the alternate URL was built from a stale slug map. The data suggests breakage clusters at the template level, not randomly.

Caveats worth flagging. Reciprocity checks need the *rendered* HTML if annotations are injected client-side — a static crawl will under-report. And a self-referential tag must exist on every URL, or Google may distrust the whole cluster; include the self-pair in your join. We have not tested whether sitemap-delivered hreflang behaves identically here, though Google's docs imply it should.

The payoff: one join query turns a vague GSC warning into a precise list of edges to repair.