hreflang generator
hreflang is easy to write and easy to get subtly wrong — en_GB instead of en-GB, a missing x-default, a relative URL, the same URL claimed by two locales. Paste your locale and URL pairs to get all three markup formats at once, with the mistakes listed before you ship them.
Issues
How to use
- Write one line per language version: the hreflang value, a space, then the absolute URL.
- Set the x-default URL — the page to serve users whose language you do not target. Usually your global or English page.
- Read the Issues table and fix anything listed. Invalid locale codes and relative URLs cause the whole cluster to be ignored, not just the bad line.
- Copy the link tags into the
<head>of every page in the set, including the page itself — see below. - Use the Link header form for non-HTML resources, or the sitemap markup if you would rather declare the cluster once in your sitemap than in every page's head.
The two rules people break
The set must be reciprocal and self-referential. Every page in the cluster must list every page in the cluster — including itself. If example.de points at example.com but example.com does not point back, Google discards the annotation as unconfirmed. This is why the generated block is meant to be pasted identically into all of them, self-reference included: it is the only configuration that satisfies the rule automatically.
The value is a language, optionally with a region — never a country alone. hreflang="de-AT" is German as served to Austria; hreflang="at" is invalid and silently ignored. The language is an ISO 639-1 code, the region an ISO 3166-1 Alpha-2 code, joined with a hyphen — en-GB, not en_GB or en-UK (the country code for the United Kingdom is GB). A script subtag is allowed where it disambiguates: zh-Hant-TW.
Two smaller things worth knowing. Pick one declaration method — head tags, HTTP header, or sitemap — because conflicting declarations across methods produce unpredictable results. And every URL in the set must be canonical and self-canonical: an hreflang alternate that carries a rel=canonical pointing somewhere else is a contradiction, and the canonical wins.
FAQ
Do I need x-default?
It is not mandatory but it is strongly recommended, and its absence is flagged here. Without it, a user whose language matches none of your alternates gets whichever version Google guesses.
Can I use a language without a region?
Yes, and often you should. hreflang="fr" covers every French speaker; add fr-CA only when you genuinely have a separate Canadian page. Listing both is fine — the more specific match wins.
Which method should I choose?
Head tags if you control the templates — simplest to verify by viewing source. Sitemap markup if you have thousands of URLs and want to avoid bloating every page's head. The HTTP header only for non-HTML files like PDFs, which have no head to put tags in.
Does hreflang consolidate ranking signals?
It is not a canonical and does not merge pages — it tells search engines which version to show to whom. Duplicate content across language versions is handled separately, and near-identical pages in the same language (en-GB vs en-US) can still be treated as duplicates if they differ only in currency.