Hreflang Tag Generator
Google’s own John Mueller has called hreflang one of the most complex parts of SEO. Most of that complexity is three rules people break silently: every version lists every version, codes must be ISO-valid, and x-default is a decision. This generator enforces all three and hands you a copy-paste block.
Enter your domain and one locale per line; get the complete, reciprocal annotation block — as HTML <link> tags for the <head> or as XML for your sitemap. The same block (with hrefs adjusted per page) goes on every version of the page, including itself. Miss one side and Google silently ignores the pair: that is the return-link rule, and it is absolute.
Hreflang Tag Generator inputs and result
How to use this calculator
- Enter your base domainThe protocol and host every localized URL shares, for example https://example.com. The generator strips a trailing slash so your paths join cleanly.
- List your locales, one per lineUse the format code | path, such as en-US | /en-us/. Codes are ISO 639-1 language (de), optionally plus an ISO 3166-1 Alpha-2 region (de-DE) or a script subtag (zh-Hans).
- Set your x-defaultAdd a line for x-default pointing at the fallback users see when they match no listed locale — usually a language selector or your primary market.
- Switch HTML or sitemap XMLChoose HTML link tags for the head, or XML annotations for your sitemap. Pick one method sitewide; never run both at once.
- Copy the block onto every versionThe generated set, with hrefs unchanged, goes on every sibling page including itself. That self-reference and the return links are what make Google honor the pair.
RGM Expert Says
We built this generator because hreflang fails quietly, and quiet failures are the expensive kind. A client launches German and French versions, ships the markup, and waits for the right pages to surface in the right markets — and nothing changes, because one side of the pair never listed the other. Search Console shows no error. The annotations are simply discarded. Putting a correct, reciprocal block in front of a team usually ends a month of guessing in an afternoon.
The single rule we repeat on every engagement is one method, sitewide. Teams reach for a plugin on the head tags, then someone adds sitemap annotations later, and now two sources disagree per template. Google resolves the contradiction by trusting neither. Past roughly ten templates we move clients to sitemap XML from one generator script, so there is one artifact to deploy and nothing to drift. The HTML output here is for the small-site case where head tags are still the cleaner choice.
The code validation matters more than it looks. en-UK is the classic example — the United Kingdom is GB in ISO 3166, so en-UK is invalid and serves nothing, with no warning anywhere. We have audited eight-figure international sites whose entire hreflang setup was inert for exactly that reason. This tool flags every malformed code as you type, which is the cheapest international-SEO win we know of.
How it works
hreflang is not a calculation; it is a set of constraints. The generator turns your locale list into a valid, reciprocal annotation block and enforces the three rules that decide whether search engines honor it.
- Reciprocity — page A must annotate B and B must annotate A back, or the pair is ignored with no error.
- x-default — the deliberate fallback for users matching no listed locale; usually a selector or primary market.
- Valid code — language alone (de), language-region (de-DE), or language-script (zh-Hans); en-UK is invalid because the UK is GB.
hreflang operates only between indexed pages. If a version is noindexed, canonicaled to another language, or quality-declined, no annotation will serve it — debug indexing first. See Google’s localized-versions guidance.
Why correct hreflang is mostly about avoiding silent failure
The hard part of hreflang is not writing the tags; it is that every common mistake fails without telling you. An invalid code, a missing return link, a canonical pointing at the wrong language — each one quietly removes a page from the set, and Search Console stays green. Teams burn weeks debugging ‘rankings’ when the real problem is that their carefully built annotations were discarded the day they shipped.
The return-link rule is the one to internalize. hreflang is a handshake: if your English page points at the German page, the German page must point back, or the relationship does not exist. That is why the generator emits the full set including the self-reference — you paste the same logic on every sibling so the handshakes always close. Skip the self-reference and you invite partial processing.
Finally, choose one delivery method and hold to it. Head tags and sitemap annotations are equivalent in effect but not in maintenance: head tags rot as templates and plugins change, while sitemap XML from a single script gives you one artifact to deploy and audit. Small sites can stay on head tags; large ones should move to the sitemap. Mixing the two is how contradictions creep in.
The hreflang mistakes that fail silently
From RGM international-SEO audits, these are the failures we find most often — ranked by how quietly they break. None of them throws a Search Console error.
| Mistake | Why it fails | Fix |
|---|---|---|
| Invalid code (en-UK, en-EU) | Code is not valid ISO; serves nothing | Use en-GB; validate every code |
| Missing return link | Pair is non-reciprocal, so discarded | Put the full set on every version |
| No self-reference | Invites partial processing | Include the page’s own locale in its set |
| Cross-language canonical | Canonical overrides hreflang | Self-canonicalize each version |
| Annotating unindexed pages | hreflang only links indexed URLs | Fix indexing before markup |
What international-SEO practitioners say
hreflang is one of the most complex aspects of SEO, and small implementation errors are easy to make and hard to spot without careful validation.
Most hreflang problems are not about the tags themselves but about reciprocity, valid codes, and making sure the alternate pages are actually indexable.