Hreflang tags tell search engines that several URLs are language or region-specific versions of the same content, so the right variant gets served to the right searcher instead of search engines guessing or treating separate-language pages as unrelated competitors. This tool builds a complete, correctly-formatted set of hreflang <link> tags, including the easy-to-forget reciprocal and x-default entries.
The core idea: annotating equivalence, not just translation
Hreflang doesn't translate anything and doesn't create any content — it's purely an annotation layer that tells search engines "these separate URLs represent the same underlying page, adapted for different languages or regions." Without that annotation, a site with an English and a French version of the same article looks to a search engine like two entirely separate, unrelated pages that happen to share a similar topic — potentially competing against each other in search rankings rather than each serving its own intended audience cleanly. With correct hreflang annotation, a search engine understands the relationship and serves the right variant to the right searcher based on their language and location settings, while still letting both variants exist and be discoverable independently.
Why the "every page links to every page, including itself" rule exists
This is the single detail that trips up more hreflang implementations than anything else: the complete set of hreflang links — one entry per language/region variant, plus a self-referencing entry for the current page — needs to appear, identically, on every variant page in the cluster. It's not enough for the English page to link to the French and Spanish versions; the French page needs that exact same complete set (English, Spanish, and a self-reference back to French), and so does the Spanish page. This symmetry requirement exists because search engines treat hreflang as a bidirectional relationship — a mismatched or missing reciprocal link is confusing evidence about whether the relationship is real, and Google's documented behavior when it encounters an inconsistent, non-reciprocal cluster is often to ignore the annotation entirely rather than guess at which direction is correct. This tool generates the complete set as one block specifically because the same block is meant to be placed, unmodified, into every one of the listed pages — not customized per page, which is exactly where manual hand-editing tends to introduce the inconsistency that breaks the whole cluster.
Language codes versus region codes, and why the distinction matters
A hreflang value can be a language code alone (en for English generally, fr for French generally) or a language-region pair (en-us for English as used in the United States, en-gb for English as used in the United Kingdom, pt-br for Portuguese as used in Brazil versus pt-pt for Portuguese as used in Portugal). Using a language-only code when you actually have region-specific variants throws away real targeting precision — en alone can't distinguish a page meant for US English speakers from one meant for UK English speakers, even if the underlying content genuinely differs in spelling conventions, currency, or region-specific detail. Conversely, using a region code without ever verifying it's an actual, valid ISO region code is a common source of silently broken hreflang, since a typo'd or invalid code simply won't match any real searcher's locale and the entry becomes dead weight.
x-default: the fallback that isn't strictly required, but should be included anyway
x-default specifies which URL to serve a searcher whose language and region don't match any of the specific variants explicitly listed — someone browsing in Japanese hitting a site that only has English and French variants defined, for instance. It's technically optional per the hreflang specification, but Google explicitly recommends including it, and the practical reason is straightforward: without an x-default, there's simply no defined behavior for that unmatched-locale searcher, and different search engines may handle the gap inconsistently. Most commonly, x-default points either to a language-selector landing page or to the site's primary, default-language version — whichever makes more sense for how the specific site actually wants to greet a visitor whose locale it can't confidently match.
Common ways hreflang silently breaks
Pointing to a URL that returns a 404, has since been redirected, or was simply typo'd — since hreflang entries aren't visible anywhere in the normal page UI, this kind of breakage produces zero visible symptom and can persist unnoticed for a long time. Using an invalid or malformed language/region code, which search engines simply can't match to any real searcher and will quietly ignore. Letting the hreflang set drift out of sync across variant pages as content gets added, removed, or restructured over time — a new region variant added six months after the original set was set up, with the reciprocal update forgotten on the existing pages, is exactly the kind of gradual, easy-to-miss inconsistency that breaks a hreflang cluster without anyone noticing until organic traffic patterns for a specific region look off.
Verifying it actually worked
Google Search Console's International Targeting report is the most reliable way to catch hreflang errors on a live, already-indexed site, since it specifically flags broken reciprocal links, unrecognized codes, and other structural problems Google's crawler encountered while trying to interpret the annotation. Because none of these problems are visible on the page itself, periodic verification through Search Console — not just a one-time check when hreflang is first implemented — is worth building into a regular technical SEO review, especially after any change to a site's URL structure or the addition of a new language variant.
The output from this tool is meant to be pasted, unmodified, into the <head> of every single page listed in it — including the page it's being pasted into, via its own self-referencing entry. Don't hand-edit the block differently per page; that's exactly the kind of drift that breaks the reciprocal-link requirement described above.