Hreflang Tag Generator — International SEO, x-default Included

Hreflang only works when annotations are reciprocal

The commonest hreflang failure is a broken promise. If your English page declares a German version at https://example.com/de/, that German page must declare the English version right back. Where the return annotation is missing, search engines discard the relationship — and in practice often the whole cluster — so the tags do nothing at all.

This is why hreflang setups so often look correct and achieve nothing. Nothing on the page is malformed; the markup simply is not answered from the other end, and there is no error message anywhere to tell you.

Every page in the group lists every page in the group

It follows that a self-referential annotation — a page pointing at its own URL — is required, not optional. Omitting it is the second most common failure.

So three localised versions do not mean one tag each. Every page carries the same complete block. With English for the US, English for the UK and Spanish for Spain, plus a fallback, each of the three pages carries all four lines:

<link rel="alternate" hreflang="en-us" href="https://example.com/en-us/contact" />
<link rel="alternate" hreflang="en-gb" href="https://example.com/en-gb/contact" />
<link rel="alternate" hreflang="es-es" href="https://example.com/es/contacto" />
<link rel="alternate" hreflang="x-default" href="https://example.com/contact" />

Identical on all three pages. Note that x-default is a fallback rather than a fourth locale, which is why three versions produce four lines.

Language and region codes

The value is a language code from ISO 639-1 — en, fr, hi — optionally followed by a region from ISO 3166-1 Alpha 2, such as en-US or fr-CA. The codes are case-insensitive, though the convention is lowercase language and uppercase region.

Two traps are worth naming. The region refers to a country, not a language: en-GB means English as served to the United Kingdom, so it targets location rather than dialect. And the code for the United Kingdom is GB, not UK — en-uk is invalid and silently ignored, which is among the most frequent errors in real implementations. Language alone is always valid; a region alone never is.

x-default is the fallback for unmatched visitors

When a visitor's language and region match none of your listed versions, x-default is what gets served. It usually points at a language-selector page or an international version rather than at any one localised page.

It is genuinely useful and frequently omitted. Without it, a visitor who matches nothing gets whichever version the search engine guesses at, which is rarely the one you would have chosen.

Where the annotations can live

There are three valid placements, and you should pick one rather than mixing them for the same set of pages:

• HTML head — link elements, as generated here. The most common approach and the easiest to inspect.
• HTTP Link headers — the only option for non-HTML files such as PDFs, which have no head to put anything in.
• XML sitemap — annotations attached to each URL entry. Far more compact for a large site, since one file describes every relationship instead of every page repeating the block.

Two further requirements apply whichever you choose: URLs must be absolute, and each should be the canonical version of that page. A page canonicalised to a different URL undercuts its own hreflang, since you are simultaneously telling search engines this page is the right one for German speakers and that a different URL supersedes it.

See also the robots.txt generator and sitemap.xml generator.