An hreflang tag generator is only useful if it enforces the rules that actually break international sites, and there are three: the codes must be real, every page in a group must link to every other page in the group including itself, and one version should usually be marked as the fallback. This page generates the markup and checks all three before you copy anything. Everything runs in your browser, so nothing about an unlaunched locale leaves the tab.
Arb Digital's SEO team audits international sites regularly, and the failure is nearly always the same one. The markup exists, the codes look plausible, the tags are in the right place — and the return links are missing, so search engines discard the whole set. Nothing in Search Console says "invalid". The pages simply do not swap in the right locale, and everyone assumes hreflang does not work. It does. It just has a stricter contract than most SEO markup.
What This Hreflang Tag Generator Does
List your locales and their URLs, one per line, and the tool builds the complete annotation set in whichever of the three supported formats you need: HTML link elements for the head of a page, an HTTP Link header for non-HTML files such as PDFs, or the xhtml:link markup used inside an XML sitemap. It also validates as it goes.
Each code is split into its language, optional script and optional region parts and checked against the code lists search engines accept: ISO 639-1 for the language, ISO 15924 for the script, ISO 3166-1 alpha-2 for the region. Codes that are the wrong shape entirely — a region with no language, an invented country code, a three-letter language — are errors. Codes that are merely unconventional, such as an uppercase language subtag, are corrected in the output and reported as warnings, because hreflang values are case-insensitive but consistency makes an audit far easier.
Then the structural checks. The page URL you supply at the top is matched against the set to confirm a self-reference exists. Duplicate codes are errors, since two tags claiming the same locale give a crawler no way to choose. Duplicate URLs across different codes are warnings, because that is sometimes deliberate and sometimes a copy-paste mistake. A missing x-default is a warning, and relative URLs are errors.
How to Use It
- Enter the URL of the page you are marking up. This is what the self-reference check compares against, so use the exact canonical form including the trailing slash.
- List every version of that page. One line each: the locale code, then the absolute URL. Include the page you are on — that line is the self-reference.
- Add an x-default line pointing at whichever version should serve users whose language and region you do not target.
- Choose the output format and click Generate. The verdict tells you whether the set is complete, and the report lists every error and warning with the line it came from.
- Repeat for every page in the group — or better, generate the set once and have your templates output the same block on all of them, with only the self-reference changing position.
How the Codes Are Validated
An hreflang value is a language tag, and language tags have a defined grammar: a primary language subtag, optionally a script subtag, optionally a region subtag, in that order. Search engines accept a useful subset of that grammar — language alone, language plus region, or language plus script plus region — and reject the rest. The full grammar is specified in RFC 5646, Tags for Identifying Languages, and the subset that matters for search is described in Google's documentation on localized versions of a page.
Two mistakes account for most invalid codes in the wild. The first is en-uk. There is no country code UK in ISO 3166-1; the United Kingdom is GB, and en-gb is the correct tag. UK is reserved and will not be recognised, so a British site marked en-uk is running unrecognised markup on every page. The second is using a region on its own, such as us or ca. The language subtag is mandatory and the region is the optional part, so a region-only value is either invalid or, worse, silently read as a language — ca is a valid language code for Catalan, which means a set meant for Canada may quietly target Catalan speakers instead.
A related trap is the region subtag as a whole. It describes the country of the audience, not the country the content was written in or the country the server sits in. es-mx means Spanish for readers in Mexico. It does not mean "Mexican Spanish" as a dialect label, and it will not be shown to Spanish speakers elsewhere unless a broader es version also exists. That is why a language-only tag is usually worth including alongside the regional ones: it catches everyone the specific targets miss.
The Return-Link Rule, and Why It Breaks Everything
This is the rule the whole feature depends on, and it is the differentiator worth understanding properly: hreflang annotations must be reciprocal. If page A declares page B as its French alternate, page B must declare page A as its English alternate. If it does not, the annotation is unconfirmed and search engines may ignore it — not just the one link, but potentially the entire set for those pages.
The reason is straightforward once you think about it as a trust problem. Anyone can add a tag on their own page claiming that some other page is its French version, including on a domain they do not control. Without a return link, that claim is unverifiable and would be trivially abusable to hijack a competitor's rankings in another market. The return link is the confirmation: both pages agree they belong to the same group, and only then does the pair count.
In practice this means every page in a group carries the same block of tags, and that block includes a tag pointing at the page itself. A group of five locales has five tags on each of five pages — twenty-five in total, not twenty. The self-reference is not decoration and it is the part hand-written implementations drop most often, usually because the person writing it thinks of the tags as "links to the other versions". They are not. They are a declaration of the whole group, published identically by every member.
Two corollaries follow. First, if you add a sixth locale, every existing page needs updating, which is why generating these tags from a shared template or a locale table is the only maintainable approach beyond a handful of pages. Second, the URLs in the annotations must match exactly across pages — a trailing slash on one page and not on another produces two different URLs, the return link does not match, and the set silently fails. Our URL parser is useful for spotting exactly where two nearly-identical URLs diverge.
What x-default Is Actually For
The x-default value marks the version to serve when none of the other annotations match the user. It is not "the English version" and it is not "the homepage", although it is frequently both by coincidence. It is the fallback: a language selector page, a global version, or whichever locale you would rather show a visitor from a country you do not specifically target.
It is optional, and this tool warns rather than errors when it is missing, but omitting it means visitors outside your targeted locales get whichever version the search engine guesses at. For a site targeting en-us, en-gb, fr-fr and de-de, that covers four countries and leaves the rest of the world to chance. The x-default tag participates in the same reciprocity rule as everything else: it belongs in the block on every page of the group, not only on the fallback page itself.
Three Places to Put Them, and Never Mix
Hreflang annotations can be delivered in exactly three ways: link elements in the HTML head, an HTTP Link header, or xhtml:link elements inside an XML sitemap. All three are equally valid and search engines treat them the same. The HTML method is the most common and the easiest to debug because it is visible in view-source. The header method exists for files that have no head to put tags in, such as PDFs. The sitemap method scales best for very large sites because it keeps the annotations out of the page payload entirely — a group of ten locales adds ten tags to every page's head, which is real weight on a site with a hundred thousand pages.
Choose one and stay with it. Using two methods at once is not additive; it is a source of contradictions, because the two sets drift the moment somebody updates one and forgets the other, and there is no rule saying which wins. If you go the sitemap route, the annotations have to sit inside the same <url> entry as the <loc> they describe, and the file still has to satisfy every ordinary sitemap rule — run the result through our sitemap validator and build the file itself with the XML sitemap generator. For the HTML method, the tags belong in the head alongside your other meta elements, which our meta tag generator produces.
Hreflang and Canonical Have to Agree
The single most damaging conflict in international SEO is an hreflang set that fights the canonical tags. Each locale page should carry a self-referencing canonical — the French page canonicalises to itself — and the hreflang block declares the group. Point the French page's canonical at the English page instead, as a well-meaning attempt to consolidate duplicate content, and you have told search engines that the French page should not be indexed at all, while simultaneously telling them it is the French version of a group. The contradiction is resolved by ignoring the hreflang.
The same logic applies to noindex. A page excluded from the index cannot be served as anyone's alternate, so a noindex on one locale removes it from the group and, because the return link from that page no longer counts, weakens the rest of the set too. Check the rendered head of each locale before assuming the markup is the problem — and check how the result reads in search with our SERP snippet preview, since a locale showing the wrong language in its title is often the first visible symptom.
Language Versus Region: Choosing Your Granularity
More locales is not better. Every additional locale multiplies the tags on every page, the templates to maintain, and the ways the set can break. The useful question is whether the content genuinely differs by region or only by language. If your Australian and British pages are identical English apart from a currency symbol, en-au and en-gb as separate entries buy you very little and cost you maintenance. If pricing, shipping, legal terms or product availability differ, they are genuinely different pages and the regional split earns its keep.
A practical middle ground is a language-only tag as the base, plus regional tags only where the content really diverges: en for everyone, with en-us and en-au layered on top where the differences matter. Search engines prefer the most specific match and fall back to the language-only version otherwise, which is exactly the behaviour you want. If you are also marking up regional organisation or product data, our schema markup generator covers the structured-data side of the same problem.
Arb Digital plans international site structure, implements hreflang and canonical signals that agree with each other, and tracks performance per locale rather than as one blended number.
SEO Services Talk To Our TeamCommon Mistakes to Avoid
- Leaving out the self-reference — every page must include a tag pointing at itself, or the group is incomplete and may be discarded.
- Using
en-uk— the ISO 3166-1 code for the United Kingdom is GB. UK is not recognised and the tag does nothing. - Writing a region without a language — the language subtag is mandatory, and codes like
cawill be read as a language rather than a country. - Canonicalising one locale to another — it removes that page from the index and breaks the return link, taking the rest of the set down with it.
- Mixing delivery methods — HTML tags plus sitemap annotations plus HTTP headers drift apart, and nothing defines which set wins.
Related Free Tools From Arb Digital
Build the rest of the head with the meta tag generator, produce the sitemap that carries these annotations with the XML sitemap generator, check that file with the sitemap validator, compare two near-identical URLs with the URL parser, preview how a locale appears in results with the SERP snippet preview, or add structured data with the schema markup generator. Everything we publish is in the free online tools hub.
Frequently Asked Questions
Annotations must be reciprocal. If page A declares page B as an alternate, page B must declare page A in return. Without that confirmation the annotation is unverified and search engines may ignore the whole set, because otherwise anyone could claim another site's page as their alternate.
Yes. The self-reference is required, and it is the part most hand-written implementations leave out. A group of five locales therefore carries five tags on each of the five pages.
Because UK is not an ISO 3166-1 country code. The United Kingdom is GB, so the correct tag is en-GB. A site using en-UK is publishing an unrecognised value on every page.
It marks the fallback version for users whose language and region match none of your other annotations. It is optional but recommended, and like every other tag in the group it must appear on every page, not only on the fallback page.
Yes. HTML link elements, HTTP Link headers and sitemap annotations are all valid and treated equally. Choose one method and use it consistently, because two methods drift apart and nothing defines which one wins.
Yes. Each locale page needs a self-referencing canonical. Pointing one locale's canonical at another removes it from the index and breaks the return link, which weakens the annotations for the rest of the group.
A language alone is enough, and is often the better choice. Add a region only where the content genuinely differs by country, since every extra locale multiplies the tags to maintain and the ways the set can break.
No. Validation and tag generation both run in your browser, so you can safely paste URLs for locales that have not launched yet.
