Hreflang Tags: The Return-Link Mistake That Breaks Them

Hreflang is one of the few pieces of technical SEO that's genuinely all-or-nothing: a set of tags that's 90% correct behaves the same as one that's completely missing. Here's how to use the generator to avoid that, and what to check if you already have hreflang live.

Use the Hreflang Tag Generator →

What Hreflang Actually Does

If your site has an English version and a Spanish version of the same page, hreflang is how you tell Google (and Bing, and Yandex) that the two pages are alternate versions of one another rather than duplicate or unrelated content. Get it right, and a searcher in Madrid sees your /es/ page in results while a searcher in Chicago sees /en/ — same content, right language, no duplicate-content penalty for having both.

The tag itself is simple: a <link rel="alternate" hreflang="..." href="..." /> element in the page's <head>, or an equivalent block inside your XML sitemap. The language code follows ISO 639-1 (two letters, like en or es), optionally paired with an ISO 3166-1 Alpha-2 region code (en-US, en-GB), joined with a hyphen.

Why "Mostly Right" Isn't Good Enough

Google's own guidance on localized versions is explicit that hreflang annotations must be confirmed from both sides: if page A points to page B, page B has to point back to page A. Semrush's breakdown of the most common hreflang errors puts missing return (reciprocal) links right alongside missing self-references as the two mistakes most likely to make Google disregard the entire set — not just the one broken link, the whole annotation for that cluster of pages.

That's the part that trips people up. A three-language hreflang set — English, Spanish, Italian — needs nine individual <link> tags spread across three pages (each page lists all three languages, including itself) for full reciprocity. Add a fourth language and it's sixteen tags across four pages. Doing that by hand, especially across a CMS where each language version might be edited by a different person or updated at a different time, is exactly the kind of repetitive, easy-to-get-subtly-wrong task that produces silent failures — the page still loads fine, nothing looks broken, and the hreflang set just quietly doesn't work.

How to Use the Generator

Add one row per language/region version of the page, each with its correct code and full absolute URL. The tool builds every page's tag block from that same shared list, which is what guarantees reciprocity and self-reference automatically — every block includes every URL, including its own. Turn on x-default if you want to control which version Google shows a visitor whose language doesn't match anything you've listed (recommended for most multi-region sites; skip it only if you're fine with Google choosing on its own).

Paste the same complete block into the <head> of every corresponding page in the language cluster. Each page must carry the full set: a self-reference plus a link to every alternate version (and x-default when used). The references must also be reciprocal — if page A links to page B, page B must link back to page A — or Google may ignore the annotations. The dropdown lets you inspect each page in the cluster, but the generated block is intentionally identical for every page. See Google's localized-versions documentation for the implementation requirements. If you'd rather declare hreflang centrally instead of editing every page's <head>, use the sitemap-based output instead: it produces an XML sitemap with xhtml:link alternates per URL, a valid alternative Google supports. Pick one method per URL and don't mix both, since conflicting declarations from two sources add confusion rather than clarity.

Checking Hreflang You Already Have Live

If hreflang is already on your site and you're not sure it's correct, the second tool on this page — the reciprocity checker — is built for exactly the failure mode above. Paste the <head> source (or just the relevant <link> tags) for each language version, and it checks, across the pages you gave it: whether each page references itself, whether every outbound link has a matching link back, whether any code is malformed, whether any href is a relative path instead of an absolute URL, and whether the same destination URL is claimed under two different language codes.

One honest limitation: the checker can only verify reciprocity between pages you actually paste in. If your site has ten language versions and you paste three, it will tell you those three look correct without being able to confirm the other seven link back correctly too — for a full audit, paste every version, or run a crawler like Screaming Frog's hreflang audit across the whole site.

Other Ways Hreflang Quietly Breaks

Beyond reciprocity, a few other mistakes show up constantly in the wild. Pointing every language version's rel="canonical" tag at one "main" version — instead of each page canonicalizing to itself — directly contradicts the hreflang set and can cause Google to treat only the canonical target as real. Using relative URLs (/es/page instead of https://example.com/es/page) is technically invalid per the spec and unreliable in practice. And adding hreflang to a page that's blocked by robots.txt or set to noindex means crawlers can't follow the return link on that page at all, which breaks reciprocity for every page that points to it — even ones that are otherwise configured perfectly.

Use the Hreflang Tag Generator →