Hreflang Tag Generator

What it does

The Hreflang Generator turns a list of locale-and-URL pairs into the matching <link rel="alternate" hreflang="..."> tags, including the x-default declaration that points search engines at the URL to serve when no locale matches the user’s preference. Add a row per locale, set the URL each one serves, and the generator emits the full alternate-link block ready for the head of every page in the set.

Common situations

You operate a site with English (UK), English (US), French (FR), and German (DE) versions of the same content. Each page needs to declare every other version as an alternate so Google serves the right version to the right region. The generator builds the four-way reciprocal block in one pass — paste it into all four pages.

You have a single English homepage that is the canonical landing for international visitors but you also have French and Spanish versions. The English page should serve as x-default (the fallback for any locale not explicitly mapped) plus declare itself as en and reference the French and Spanish alternates. Without x-default, visitors from unmapped locales get whichever version Google guesses.

A migration is splitting a single multilingual site into separate per-language sites on different domains. The hreflang block now needs to declare cross-domain alternates — https://example.com/, https://example.fr/, https://example.de/. Cross-domain hreflang works the same way as same-domain; the URLs just live elsewhere. The generator does not care about the domain, only that each URL is absolute.

You are auditing a site where the international SEO is underperforming and you suspect the hreflang implementation. Typical mistakes: incomplete reciprocal declarations (page A says it has alternate B, but page B doesn’t say it has alternate A), wrong locale codes (using en-GB correctly but fr for “French in France” instead of fr-FR), or missing x-default. The generator forces correct structure; comparing the generator output against what is on the live site surfaces the gaps.

What you need to know

Hreflang tells search engines that a page has versions in other languages or regions, and which version to show in which locale. It is not a ranking signal — it is a presentation signal. Google uses it to decide which version of a page to show in which region’s SERPs.

Locale codes follow BCP 47. The standard pattern is two-letter language plus optional two-letter region: en (any English), en-GB (UK English), en-US (US English), fr-FR (French in France), fr-CA (French in Canada), de (any German), de-AT (Austrian German). Region without language (-GB) is invalid; language alone is fine. Three-letter codes (spa, por) are valid but uncommon — use the two-letter forms unless you have a specific reason.

The x-default declaration tells Google which URL to serve when no other locale matches. If a visitor is from Brazil and your hreflang set covers en-GB, en-US, fr-FR, de-DE — none of these match Portuguese-Brazilian — x-default is what Google will fall back to. Always include x-default, usually pointing at the most-trafficked or most-generic version (often the English en-GB or en-US page).

Reciprocity is mandatory. Every page in a hreflang set must declare every other page in the set, including itself. So if you have four locale URLs, every one of those four pages must contain all four alternates. Most hreflang errors in the wild are non-reciprocal declarations — page A says it has alternates B and C, but B and C do not declare A. Google ignores non-reciprocal hreflang.

There are three places hreflang can live: in HTML <link> tags in the head, in HTTP Link headers, and in XML sitemaps. The HTML approach (what this generator emits) is the most common. The HTTP header approach is useful for non-HTML resources (PDFs). The sitemap approach is useful at scale because it puts all the relationships in one file rather than duplicated across thousands of pages. The three are equivalent — pick one, do not mix.

Frequently asked questions

Do I need hreflang if my site has only one language?

No. Hreflang is only meaningful when there are multiple language or regional versions of the same content. A single-language site does not benefit from hreflang and adding it adds complexity for no gain.

What’s the difference between language-only (en) and language-region (en-GB)?

Language-only matches all regions speaking that language. en matches British, American, Australian, Indian, Canadian, and every other English-speaking visitor. Language-region (en-GB) matches only that specific region. Use language-only when you have one English page for all English speakers; use language-region when you have separate pages targeting specific regions.

What does x-default do?

It declares the fallback URL for visitors whose locale doesn’t match any other declared alternate. If your set covers en-GB, fr-FR, de-DE, a visitor from Spain will be served the x-default URL because Spanish doesn’t match any declared locale. Always include x-default — without it, Google guesses, and the guesses are unreliable.

Can the same URL be declared for multiple locales?

Yes — useful when one English page serves multiple English-speaking regions. Declare it as en-GB, en-US, en-AU, etc., all pointing to the same URL. Google will serve that URL to all those regions.

Where should hreflang tags go in the HTML?

In the <head>, alongside other link tags. Order doesn’t matter. The convention is to place hreflang after canonical and before other resource links.

How many alternates can I declare?

There is no hard limit, but pages with hundreds of alternates start to feel unwieldy. For multilingual sites with many regional variants, the sitemap approach is cleaner — keep the HTML to canonical and a few key alternates, put the full hreflang graph in the sitemap.

Does hreflang affect rankings?

No, only presentation. A page does not rank better because it has hreflang; it ranks differently in different regions because Google now knows which version to serve.

Do I need hreflang if I’m using a CDN that does geographic routing?

Yes. CDN routing changes which server returns the content; hreflang tells Google which URL to show in search results. They serve different functions. Your hreflang should declare the URLs that Google will serve as search results, regardless of how the CDN routes the underlying responses.

Common problems

Problem: Search Console reports “no return tags” errors.

The most common hreflang error: page A declares alternate B, but page B does not declare A in return. Hreflang requires complete reciprocity — every page must declare every other page in the set, including itself. Search Console’s International Targeting report flags missing return tags per URL pair.

Problem: Wrong language version is showing in SERPs.

Either hreflang is missing, the locale codes are wrong, or Google has decided your declarations are unreliable (typically because of non-reciprocal errors elsewhere in the set). Verify all alternates are reciprocal and the locale codes are valid BCP 47.

Problem: x-default is set but Google still serves the wrong default for unmatched locales.

Check that x-default points to a page that Google can crawl and index. If the x-default URL is canonicalised to a different URL, blocked in robots.txt, or returns a non-200 status, Google falls back to picking among the other alternates rather than honouring x-default.

Problem: Hreflang in sitemap and hreflang in HTML conflict.

If you implement hreflang in both places, they must agree. When they disagree, Google’s behaviour is unpredictable. Pick one implementation method and stick with it. Sitemap-only is cleanest for sites with many alternates; HTML-only is fine for fewer than ~20 alternates per page.

Problem: Locale code en-UK is not working.

The correct ISO 3166-1 country code for the United Kingdom is GB, not UK. en-UK is invalid; en-GB is correct. This is the single most common locale-code error.

Tips

• Always include x-default. The set is incomplete without it.
• Validate the implementation with Search Console’s International Targeting report (Settings → International Targeting). It is the canonical source for hreflang errors and reciprocity issues.
• For sites with more than a dozen alternate URLs per page, move hreflang into the XML sitemap. The HTML version becomes unmanageable at scale.
• Reciprocity must be exact. Page A declares en-GB for itself and fr-FR for B. Page B must declare en-GB for A and fr-FR for itself. Symmetrical, complete.
• When migrating URLs, update hreflang at the same time. Stale hreflang pointing at redirected URLs is one of the harder international SEO bugs to spot because Search Console reports it as “redirect” rather than as broken hreflang.

Related tools in this suite

The Page SEO Audit reports the hreflang tags found on a page so you can verify what is actually being served. The Sitemap.xml Generator is the right next stop if you decide to move hreflang from HTML to sitemap-based at scale.

What this looks like at scale

A four-locale site with twenty pages has eighty hreflang relationships. A four-locale site with two thousand pages has eight thousand. Maintaining them by hand or in templates is feasible up to a few hundred URLs; beyond that, the hreflang declarations should be derived from the data layer (which posts have which translations) and emitted automatically. That is part of what the systems we build typically include for clients who operate internationally.

Take it further

If a multilingual site is consistently flagged for international SEO issues in Search Console, the underlying problem is usually that hreflang is being maintained manually and drifting. Start a conversation about how to derive it from the data layer instead.