Hreflang Tag Generator
Build reciprocal hreflang annotations for every locale in your site, in HTML, sitemap or HTTP header form, with validation for the mistakes that break most implementations.
Photo by NASA on Unsplash
Hreflang tag generator
| Language | Region | URL |
|---|
Key takeaways
- Hreflang selects which version to show, not how well the group ranks.
- Relationships must be reciprocal and every page must reference itself, or the annotation is ignored.
- en-UK is invalid — the country code for the United Kingdom is GB.
What hreflang does and does not do
The hreflang annotation tells search engines that several URLs are the same content targeted at different languages or regions, and which one to show to which audience. Google introduced it in 2011 to solve a specific problem: near-duplicate pages in different languages competing with each other, and users landing on the wrong regional store.
It does swap the URL shown in results based on the user’s language and location signals, and it consolidates the group so the variants are not treated as competing duplicates.
It does not boost rankings, translate anything, or act as a redirect. It is a hint about which version to display, not a directive about which to rank. Bing supports it; Yandex supports it; Baidu ignores it in favour of content-language.
Getting the syntax right
The value is a language code, optionally followed by a region:
- Language: ISO 639-1 two-letter code —
en,fr,de. Required. - Region: ISO 3166-1 Alpha 2 country code —
US,GB,CA. Optional, and it means country, not language. - x-default: the fallback for users whose locale matches nothing else. Strongly recommended.
Three common errors account for most broken implementations:
| Wrong | Right | Why |
|---|---|---|
hreflang="uk" for the UK | en-GB | uk is the Ukrainian language |
hreflang="en-UK" | en-GB | The ISO country code for the United Kingdom is GB |
hreflang="US" alone | en-US | A region cannot appear without a language |
The reciprocity rule
Hreflang must be bidirectional. If the English page points to the French page, the French page must point back to the English one. Any set of pages that reference each other must all carry the complete list, including a self-referencing tag.
A missing return link invalidates the whole relationship — Google simply ignores the unconfirmed annotation. This is by far the most common failure, because adding a new locale means updating every existing page, not just the new one.
<!-- On EVERY page in the group, including itself -->
<link rel="alternate" hreflang="en-us" href="https://example.com/en-us/">
<link rel="alternate" hreflang="en-gb" href="https://example.com/en-gb/">
<link rel="alternate" hreflang="fr-fr" href="https://example.com/fr-fr/">
<link rel="alternate" hreflang="x-default" href="https://example.com/">URLs must be absolute, must use the canonical protocol and host, and must match the page’s own canonical tag. An hreflang pointing at a URL that canonicalises elsewhere is self-contradictory and will be dropped.
Three ways to implement it
| Method | Best for | Trade-off |
|---|---|---|
HTML <link> tags | Small to medium sites | Simple, but head size grows as n² with locale count |
| XML sitemap annotations | Large sites, many locales | Keeps pages light and centralises maintenance; harder to debug |
HTTP Link headers | Non-HTML files such as PDFs | The only option where there is no head to put tags in |
With ten locales, HTML tags mean 100 link elements across the group. At that scale sitemap annotations are usually the better engineering choice, and this tool emits all three formats from the same table.
Pre-launch checklist
- Every page in the group lists every other page, plus itself.
- Language codes are ISO 639-1; region codes are ISO 3166-1 Alpha 2.
- An
x-defaultexists for unmatched locales. - All URLs are absolute, on the canonical host, and return 200.
- Each page’s canonical tag points at itself, not at another locale.
- No locale is blocked in robots.txt or marked
noindex. - Automatic IP-based redirects are avoided — they prevent crawling of the other versions. Suggest, do not force.
- Check the International Targeting report in Search Console after deployment.
Verify the rendered tags with the meta tag analyzer and confirm the URL forms with the URL parser.
Frequently Asked Questions
What is hreflang used for?
It tells search engines that several URLs are the same content for different languages or regions, so the right version is shown to the right user and the variants are not treated as competing duplicates.
Does hreflang improve rankings?
No. It affects which version of a page is displayed to a given user, not how highly the group ranks. The benefit is relevance and avoided duplication, not a boost.
Do I need a self-referencing hreflang tag?
Yes. Google's documentation is explicit: each page must include an hreflang entry pointing at itself alongside the entries for its alternates.
What is x-default for?
It marks the fallback URL for users whose language and region match none of your specified locales — typically a language selector or your primary market page.
Is en-UK valid?
No. The ISO 3166-1 country code for the United Kingdom is GB, so the correct value is en-GB. en-UK is silently ignored.
Should I use tags, sitemaps or headers?
HTML link tags are simplest for a handful of locales. Beyond about five locales, sitemap annotations keep pages lighter. HTTP headers are for non-HTML resources such as PDFs.
What if the return link is missing?
The annotation is ignored. Hreflang relationships must be confirmed from both sides, so every page in the set needs the complete list.
Sources & further reading
- Google Search Central: Localized versions — the reference implementation guide and reciprocity requirement
- ISO 639-1 language codes — valid two-letter language identifiers
- ISO 3166-1 country codes — valid two-letter region identifiers
- RFC 8288: Web Linking — the HTTP Link header format