• SEO
  • International
  • Reference

Hreflang mistakes that make Google ignore your translations

Missing return links, en-UK, canonicals that point home, redirecting alternates: the hreflang errors that break a cluster, and how to fix each.

The utilyx team8 min read
On this page

You translated the pricing page into German, added a row of <link rel="alternate" hreflang> tags, and shipped. A month later, people searching in German still land on the English page. Nothing in your markup looks wrong. Nothing errors. The tags are simply being ignored.

That is the uncomfortable thing about hreflang: it fails silently. A browser never reads it, so nothing breaks visibly, and a cluster with one bad link can be discarded without a single warning on the page itself. Almost every failure comes from a short list of mistakes, and Google documents nearly all of them. This post goes through that list, rule by rule, against Google's own guide, Tell Google about localized versions of your page.

One scope note before we start: everything here is about Google, because that is the engine whose rules are written down in one place. Other search engines document their own signals; check theirs before assuming they match.

What hreflang does, and what it doesn't

Hreflang tells Google that several URLs are versions of the same page for different languages or regions, so it can show each searcher the right one. The set of URLs that point at each other is usually called a cluster. Google's guide recommends it for fully translated sites, for pages where only the template is translated, and for small regional differences in one language, such as prices in pounds versus dollars.

Three things it does not do:

  • It doesn't tell Google what language a page is in. The guide says Google detects the language with its own algorithms and doesn't use hreflang or the HTML lang attribute for that. Keep lang correct for screen readers and browsers, but don't expect it to fix search.
  • It doesn't make thin translations count as separate pages. If only the navigation is translated and the main content is the same, the versions can still be treated as duplicates.
  • It doesn't redirect anyone. It influences which URL appears in results. What happens after the click is up to you.

This is the mistake that sinks most clusters, and the guide is blunt about it: "If two pages don't both point to each other, the tags will be ignored." Hreflang is a two-way handshake. If the English page lists the German one but the German page doesn't list the English one back, Google has no way to tell a genuine translation from a stranger's site claiming to be your German version.

The second half of the rule catches people who get the first half right: "Each language version must list itself as well as all other language versions." So every page in the cluster carries the same full set of tags, including one that points at itself. For a pricing page in US English, German and British English, all three pages get exactly this block:

html
<link rel="alternate" hreflang="en" href="https://example.com/pricing/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/preise/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/pricing/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing/" />

Identical on every page. That property is worth building around: generate the block from one list of locales on the server, instead of hand-writing it per template. Hand-written blocks drift the first time someone adds a locale and updates two of the three pages.

Partial clusters are allowed. Google says that if keeping every pair linked is impractical, you can leave some languages out. It suggests that newer versions at least link both ways with the main, originating version. Since the rule is about pairs of pages, the pairs that do link both ways can still work.

Language and region codes Google actually accepts

The format is a language, optionally followed by a region: de, de-CH, en-GB. The language must be ISO 639-1 (two letters) and the region ISO 3166-1 Alpha 2. Google's guide is explicit that only those two lists are supported. The common failures:

WrongWhy it failsUse instead
en-UKUK is a reserved code, not the ISO code for the United Kingdom. Google ignores it.en-GB
beA region on its own is read as a language. be is Belarusian, not Belgium.nl-BE, fr-BE
en-EUEU and UN are reserved codes, also ignored.Each country, or plain en
es-419Valid BCP 47 for Latin American Spanish, but Google lists it as unsupported.es or es-MX, es-AR…
en_USUnderscore, as in many locale files. The separator is a hyphen.en-US

Case doesn't matter to Google, though uppercase regions are the ISO convention. Scripts are supported too: zh-TW implies Traditional Chinese, and you can be explicit with ISO 15924 codes like zh-Hant or zh-Hans-US.

A trap for anyone validating codes in JavaScript: the built-in Intl API checks BCP 47, which is a different and larger standard. It will quietly fix some invalid hreflang values and pass others straight through:

js
for (const code of ["en-UK", "es-419", "en-EU", "be", "zh-hant-tw"]) {
  console.log(code.padEnd(11), "->", Intl.getCanonicalLocales(code)[0]);
}
text
en-UK       -> en-GB
es-419      -> es-419
en-EU       -> en-EU
be          -> be
zh-hant-tw  -> zh-Hant-TW

Node 26 rewrites en-UK to en-GB (CLDR treats UK as an alias), which is handy for fixing data but means it never reports the error. It accepts es-419 and en-EU, both of which Google ignores, and it happily accepts be because Belarusian is a real language. Validate hreflang against ISO 639-1 and ISO 3166-1 lists, not against Intl.

x-default is the fallback, not your main language

Google defines it narrowly: "The reserved x-default value is used when no other language/region matches the user's browser setting." It is the page for everyone you didn't plan for. Its intended use is a language or country selector, or a home page that redirects by locale, though Google allows it on any page.

Two misreadings come up often. The first is treating x-default as a label for your primary language and leaving out the matching language tag. If your English page is the fallback, it needs both hreflang="en" and hreflang="x-default", as in the block above. The second is adding it to some pages in the cluster and not others. It is part of the set, and the set must be identical everywhere.

It is optional. Without it, a searcher whose language matches nothing simply gets whatever Google would have chosen anyway. But for any site with a selector page, it's the cheapest improvement on this list.

Canonicals, noindex and redirects

Hreflang links pages that Google will index and show. Anything that stops a URL from being the indexed version of itself undermines the cluster. Google's localization guide doesn't spell all of this out, so here is what its canonicalization guide says, and what follows from it.

A canonical that points to another language

The classic version: every localized page carries <link rel="canonical" href="https://example.com/pricing/">, copied from the English template. That tells Google the German page is a duplicate of the English one and that the English URL is the one to index. Meanwhile the hreflang tags say the German page is its own version that should be shown to German speakers. The two signals contradict each other.

Google's canonicalization guide says that when you use hreflang, you should specify a canonical in the same language (or the best substitute language if none exists). In practice: each localized page is canonical to itself. The canonical tag and the self-referencing hreflang tag should contain the same URL, character for character.

Alternates that are noindex

A noindex page, via a meta tag or an X-Robots-Tag header, can't appear in search results, so it can't be the version Google picks for a searcher either. Google's localization guide doesn't single this case out, but the logic is unavoidable: listing a noindex URL as an alternate points the cluster at a page that can never be shown. Usually it's a staging locale or a half-finished translation. Remove it from the set until it's ready, on every page.

Alternates that redirect

Google's canonicalization guide describes a redirect as a strong signal that the target should become canonical. So an hreflang link to /es/ that 301s to /es-es/ points at a URL Google won't treat as the indexed page. List the final URL. The same goes for the small redirects that are easy to miss: http to https, a missing trailing slash, www to the bare domain. Every hreflang href should return 200 directly.

Relative URLs and other syntax traps

Google's wording: "Alternate URLs must be fully-qualified, including the transport method (http/https)." That rules out the shortcuts that work everywhere else in HTML:

html
<!-- Wrong: root-relative and protocol-relative -->
<link rel="alternate" hreflang="de" href="/de/preise/" />
<link rel="alternate" hreflang="de" href="//example.com/de/preise/" />

<!-- Right -->
<link rel="alternate" hreflang="de" href="https://example.com/de/preise/" />

A few smaller rules from the same guide:

  • Alternates can live on other domains. example.de and example.com/de/ are both fine. The return-link rule still applies across domains.
  • Don't combine hreflang with other attributes such as media in a single tag.
  • One URL per code. Two different URLs both claiming hreflang="de" in one set is ambiguous. Don't make Google choose.

HTML, HTTP header or sitemap: pick one

Google accepts three ways to declare a cluster and treats them as equivalent. You can use more than one, but the guide says there is "no benefit in Search" in doing so, and every extra copy is another place for the sets to disagree. Google doesn't document how it resolves a conflict between methods, which is the best argument for not creating one. Pick the method that fits your stack and use only that.

HTML link elements

The block shown earlier, in the <head> of every page. Easiest to reason about, and it ships with the page it describes. Each locale adds one tag of roughly 80 bytes to every page, which only starts to matter once you have dozens of locales.

HTTP Link header

For files that have no <head>, such as PDFs. The header lists the same full set, comma-separated:

http
Link: <https://example.com/guide.pdf>; rel="alternate"; hreflang="en",
      <https://example.com/de/guide.pdf>; rel="alternate"; hreflang="de",
      <https://example.com/uk/guide.pdf>; rel="alternate"; hreflang="en-GB"

XML sitemap

Best for large sites, because it keeps the sets out of your templates entirely. Declare the xhtml namespace, then give every <url> the complete set as <xhtml:link> children, including the one that matches its own <loc>. Yes, that means the set repeats once per URL:

xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/pricing/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/pricing/"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise/"/>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://example.com/uk/pricing/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing/"/>
  </url>
  <url>
    <loc>https://example.com/de/preise/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/pricing/"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise/"/>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://example.com/uk/pricing/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing/"/>
  </url>
  <url>
    <loc>https://example.com/uk/pricing/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/pricing/"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise/"/>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://example.com/uk/pricing/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing/"/>
  </url>
</urlset>

Our hreflang sitemap generator builds exactly this from a page-by-locale table, and the hreflang generator produces the HTML block if you'd rather keep it in the head. Both run in your browser.

Check the whole cluster, not one page

Most of these mistakes are invisible from a single page. A page can be perfect on its own and still fail because its sibling doesn't link back, or because the URL it links to redirects. The only real check fetches every page in the cluster and compares them.

Here is a small Node script (Node 18 or later, no dependencies) that does that for HTML link elements. It fetches each URL without following redirects, then reports bad status codes, noindex, foreign canonicals, missing self-references, relative URLs and missing return links:

js
// Usage: node check-hreflang.mjs https://example.com/ https://example.com/de/ ...
// Regex parsing: fine for a quick audit of your own pages, not a general HTML parser.
const attr = (tag, name) => tag.match(new RegExp(`${name}\\s*=\\s*["']([^"']*)["']`, "i"))?.[1];

async function inspect(url) {
  const res = await fetch(url, { redirect: "manual" });
  const html = res.status === 200 ? await res.text() : "";
  const links = html.match(/<link\b[^>]*>/gi) ?? [];
  const alternates = new Map();
  let canonical = null;
  for (const tag of links) {
    const rel = (attr(tag, "rel") ?? "").toLowerCase().split(/\s+/);
    const href = attr(tag, "href");
    if (rel.includes("alternate") && attr(tag, "hreflang")) alternates.set(href, attr(tag, "hreflang"));
    if (rel.includes("canonical")) canonical = href;
  }
  const robots = `${res.headers.get("x-robots-tag") ?? ""} ${html.match(/<meta[^>]+name=["']robots["'][^>]*>/i)?.[0] ?? ""}`;
  return { status: res.status, alternates, canonical, noindex: /noindex/i.test(robots) };
}

const urls = process.argv.slice(2);
const pages = new Map();
for (const url of urls) pages.set(url, await inspect(url));

for (const [url, p] of pages) {
  const problems = [];
  if (p.status !== 200) problems.push(`returns ${p.status}; hreflang targets should return 200`);
  if (p.noindex) problems.push("is noindex");
  if (p.canonical && p.canonical !== url) problems.push(`canonical points to ${p.canonical}`);
  if (p.status === 200 && !p.alternates.has(url)) problems.push("does not list itself");
  for (const [href] of p.alternates) {
    if (!/^https?:\/\//.test(href)) problems.push(`relative URL ${href}`);
    const target = pages.get(href);
    if (target?.status === 200 && !target.alternates.has(url)) problems.push(`${href} does not link back`);
  }
  console.log(problems.length ? `✗ ${url}\n    ${problems.join("\n    ")}` : `✓ ${url}`);
}

We ran it against a deliberately broken four-page fixture: the German page lists itself with a relative URL and links to a French page that doesn't link back, the French page is canonical to the English home page, and the Spanish URL is a 301. The output:

text
✓ https://example.com/
✗ https://example.com/de/
    does not list itself
    relative URL /de/
    https://example.com/fr/ does not link back
✗ https://example.com/fr/
    canonical points to https://example.com/
✗ https://example.com/es/
    returns 301; hreflang targets should return 200

Two honest limits. It compares URLs as exact strings, so /de and /de/ count as different. That is deliberate, because one of them is a redirect. And it only reads HTML tags; for header or sitemap setups you'd parse those instead.

For a quick check of one page while you're editing templates, paste its <head> into the utilyx hreflang validator. It flags invalid codes (including en-UK, es-419 and region-only values), relative URLs, duplicate codes, a missing self-reference, a missing x-default and a canonical pointing elsewhere, then gives you a corrected block. What it can't do from one pasted page is confirm return links, status codes or noindex on the other pages. For that you need every page, which is what the script above, or your crawler of choice, is for.

Try the Hreflang validator
Free, no sign-up, and it runs in your browser.
Open the tool →