A hreflang generator turns a list of language and region variants into the markup Google needs to serve the right version of a page to the right audience. It saves typing, and it prevents syntax mistakes — but it cannot fix a broken URL map, and it will happily produce invalid annotations if you feed it bad input.
Here is what the tags do, the three legitimate ways to implement them, and the rules that decide whether Google honors them or throws them away.
What Hreflang Is and Is Not
The rel="alternate" hreflang="x" annotation tells Google that several URLs are translations or regional variants of the same content, and which audience each one is for. When Google trusts the cluster, it swaps in the appropriate URL in the results for that user.
Three things it does not do. It is not a ranking factor — correct hreflang does not lift you in the results, it changes which of your URLs is shown. It does not deduplicate content, though it does help Google understand that near-identical language variants are intentional rather than spam. And it is not universally supported: Google and Yandex use it, Bing largely relies on content-language signals instead.
The Return-Link Requirement
This is the rule that breaks most implementations, and no generator can enforce it for you.
Hreflang annotations must be bidirectional. If page A declares page B as its German alternate, page B must declare page A as its English alternate. If the return link is missing, Google treats the annotation as unconfirmed and may ignore the entire cluster — not just the one broken edge.
Two practical consequences:
- Every page in a cluster lists every page in the cluster, including itself. A self-referencing hreflang on each URL is required. Six locales means six annotations on each of the six pages, thirty-six lines total.
- URLs must match exactly. Same protocol, same host, same trailing-slash convention. An annotation pointing at
http://when the page redirects tohttps://, or at a non-canonical variant, counts as a mismatch. Always annotate the canonical, self-referencing URL.
One more interaction worth memorizing: hreflang and canonical must agree. Each locale page should canonicalize to itself. Pointing every locale’s canonical at the English version tells Google to ignore the alternates entirely, and the hreflang cluster dies with it.
Getting the Codes Right
The value is a language code, optionally followed by a region code. Language uses ISO 639-1 (two letters). Region uses ISO 3166-1 Alpha-2 (two letters) and must be preceded by a hyphen.
en— English, any regionen-GB— English, United Kingdompt-BR— Portuguese, Brazilzh-Hans— Simplified Chinese (a script subtag, valid)
Common invalid values: en-UK (the country code is GB), en_US (underscore instead of hyphen), eu used to mean the European Union (it is Basque; there is no continent code), and any bare region code such as us without a language. Region alone is never valid — language is mandatory, region is optional.
Decide early whether you need region codes at all. If you publish one Spanish version for every Spanish-speaking market, use es and stop. Adding es-MX, es-AR, and es-CO pointing at the same URL creates duplicate annotations for no benefit. Region codes earn their place only when the content genuinely differs — currency, shipping, legal terms, or product availability.
x-default: What It Is For
hreflang="x-default" marks the fallback URL for users whose language or region does not match any listed variant. It is optional but strongly recommended for any multi-region site.
Point it at whichever page best serves an unmatched visitor. Usually that is a language or country selector page, or your global English version. Do not point it at a redirect, and do not omit it and hope Google guesses — without a default, unmatched users get whatever Google infers, which is often the wrong locale.
The x-default entry follows the same return-link rule: it should appear in the annotation set on every page in the cluster, identical everywhere.
The Three Implementation Methods
Google accepts exactly three delivery mechanisms. Pick one per page type and stay consistent — mixing methods on the same URL is a common source of conflicting signals.
1. HTML head elements
Place <link rel="alternate" hreflang="…" href="…"> tags inside <head>. Simplest to inspect and debug, and what most generators output by default. The cost is page weight: a cluster of twenty locales adds twenty lines to every page. Tags must be in the head, not the body, or they are ignored.
2. HTTP response headers
Send a Link: header with the same information. This is the only option for non-HTML files — PDFs, for example, cannot carry head elements. Syntax is Link: <https://example.com/de/>; rel="alternate"; hreflang="de", with multiple entries comma-separated or repeated. Harder to audit because you need to inspect responses rather than view source.
3. XML sitemap annotations
Add xhtml:link elements to each <url> entry in your sitemap, declaring the xhtml namespace on the root element. This is the best choice at scale: the markup lives in one file instead of on every page, adds nothing to page weight, and is far easier to regenerate programmatically. The return-link rule still applies — every URL entry must list the full set, including itself. Sitemaps get large fast, so plan on splitting and using a sitemap index.
Feeding the Generator Correctly
Whichever method you choose, the generator’s output is only as good as the URL map you hand it. Build that map as a table before you touch any tool: one row per piece of content, one column per locale, each cell holding the final canonical URL. Empty cells are the interesting part — they show which translations do not exist yet, and you must not annotate a locale you have not published.
Two rules keep the map clean. Never point two different locales at the same URL, because a URL cannot be the canonical answer for two audiences at once. And regenerate the annotations from the map whenever the map changes, rather than hand-editing individual pages — manual edits are where reciprocity quietly breaks.
Validating the Output
A generator produces syntax. Validation proves the cluster works. Run these checks before and after deployment:
- Crawl and cross-reference. Use a crawler that extracts hreflang and flags missing return links, non-200 targets, and non-canonical destinations. Missing reciprocity is the number one real-world error.
- Check for redirects in targets. Every annotated URL should return 200 directly. Annotating a URL that 301s wastes the signal.
- Confirm self-references exist on every page. Easy to omit, quietly fatal.
- Watch Search Console. International targeting reporting surfaces “no return tags” and unknown-language-code errors against live indexed pages.
- Do not combine hreflang with IP-based auto-redirects. Forced redirects stop Googlebot from crawling other locales; the annotations then describe pages Google cannot reach.
Worth stating plainly: hreflang generation is not something SEO Rocket does. It is a deterministic markup job better handled by a dedicated generator plus a crawler that verifies reciprocity. What a broad platform is genuinely useful for on international sites is the layer around it — country-specific keyword indexes so a German query is scored against the German index rather than the US one, per-market rank tracking, and full-site crawls that surface the canonical and redirect problems that break hreflang clusters in the first place. Get the URL map and canonicals right, and the generator’s job becomes trivial.
