hreflang tags: return tags, x-default and the errors that void them

hreflang tags tell Google which URL is the version of a page for each language or region, so searchers land on the version that matches their language settings. Every version must list itself and every alternate with a valid code (an ISO 639-1 language, plus an optional ISO 3166-1 Alpha 2 region such as en-GB), each pair must point both ways, and an x-default entry should name the fallback page.

When those rules break, Google does not fix the annotation; it drops it. Google names missing return links and incorrect language or region codes as the most common mistakes, and alternate URLs that are not the final, canonical page are the third way to lose one.

What does hreflang mean?

hreflang is an attribute on a rel="alternate" annotation that marks another URL as the same content for a specific language, or language and region. Google uses the set to choose which version to show a searcher. It is a hint about alternates, not a language detector: Google says it does not use hreflang or the HTML lang attribute to detect a page's language.

Google recommends hreflang in three situations: the main content stays in one language but the template (navigation and footer) is translated, the same language has small regional variations (English for the US, GB and Ireland, say), or the site is fully translated. It also notes that localized versions only count as duplicates if the main content remains untranslated.

Nor does Google infer the audience from your URLs. In its own example, subdomains named en, en-gb, en-us and de are not used to determine who a page is for; the mapping exists only in the hreflang annotations you write, so a URL structure that looks obvious to you tells Google nothing on its own.

How do you add hreflang tags?

Use one of three equivalent methods: <link> elements in each page's <head>, a Link HTTP header, or <xhtml:link> entries in your XML sitemap. Google says the three are equivalent and there is no benefit in using more than one, which only makes the set harder to keep consistent.

The HTML version, for a page with English, German and a language selector, identical on all three URLs:

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

Rules that apply to every method:

• Each version lists itself as well as every other version, so the set is identical on every URL in it.
• URLs must be fully qualified, including https://: https://example.com/foo, not //example.com/foo or /foo.
• Alternates can be on different domains.
• The <link> tags must sit inside a well-formed <head>. Google says that once it finds an invalid element there, such as an <img> or <iframe>, it assumes the head has ended and stops reading further elements in it.
• Don't combine hreflang with other attributes such as media in one <link> tag.

In a sitemap, declare xmlns:xhtml="http://www.w3.org/1999/xhtml" on the <urlset>, give each URL its own <url> entry, and repeat the full set of <xhtml:link> children (including itself) under each one. Those child elements do not count toward the sitemap URL limit.

What are hreflang return tags?

A return tag is the annotation on page B that points back to page A after page A has named page B. Google's rule is that if two pages don't both point to each other, the tags are ignored. That stops someone else's site from naming itself as a version of your page.

In practice, missing return tags come from templates that are updated for one language and not the others, or from new locales added to the English pages only. Google lists "missing return links" first among the most common hreflang mistakes.

Google allows one relaxation. If a complete set of bidirectional links for every language is hard to maintain, you can leave some languages out on some pages, and Google still processes the pairs that do point at each other. Its advice is to prioritise linking new language versions both ways with your original, dominant language version.

Which language and region codes are valid?

The value is an ISO 639-1 language code, optionally followed by a dash and an ISO 3166-1 Alpha 2 region code. Only codes from those two standards are supported. The value is case-insensitive, though writing the region in uppercase (en-GB) follows the ISO convention. A region on its own is never valid.

Google also offers a practical tip for regional English or Spanish: alongside en-IE, en-CA and en-AU pages, provide a generic en page for searchers in every other English-speaking location. It can be one of the regional pages.

What is hreflang x-default?

x-default is the reserved value for the page Google should show when no listed language or region matches the searcher's browser settings. Google recommends it for fallback pages and says it was designed for language selector pages, so it works best pointing at one. It needs no language code of its own.

Add it as one more line in the same set, on every version:

<link rel="alternate" hreflang="x-default" href="https://example.com/country-selector" />

Use it for a homepage that lets people pick a language, or one that redirects by browser language. If you have no selector, point x-default at the version you want everyone else to see, usually the generic English page.

Which errors make Google ignore hreflang?

Three kinds of error void an annotation: a pair without return links, a code outside ISO 639-1 and ISO 3166-1 Alpha 2, and an alternate URL that is not the final, indexable version of the page. The table lists how each shows up and the fix.

Two of these deserve a closer look. Google's canonicalization guide says that when you use hreflang, you should specify a canonical page in the same language, and that you should not list the http:// version of pages in hreflang annotations instead of the HTTPS version. And a redirecting alternate means the URL you listed is not the page that gets indexed: Google's crawlers follow the redirect and process only the final target. List final URLs directly; the redirect chains and loops guide shows how to find every URL that still redirects, and the 301 vs 302 guide covers the right code when a locale moves. The canonical tags guide covers the canonical mistakes in full.

How do you add hreflang in Next.js?

In the App Router, set alternates.languages in metadata or generateMetadata, and Next.js outputs a <link rel="alternate" hreflang="..."> for each entry. Include the current page's own locale and an x-default in the list yourself, since the return-tag rule needs every version to list itself.

export const metadata = {
  alternates: {
    canonical: 'https://example.com/de/pricing',
    languages: {
      en: 'https://example.com/en/pricing',
      de: 'https://example.com/de/pricing',
      'x-default': 'https://example.com/pricing',
    },
  },
}

For the sitemap method, each entry returned from app/sitemap.ts accepts alternates: { languages: { es: '...', de: '...' } }. Build both from one shared list of locales and routes, so a new language cannot be added to one page and forgotten on the others.

How do you check hreflang tags?

Fetch each version and compare the sets. curl -s https://example.com/de/pricing | grep -i hreflang prints the annotations as served. Every version should print the same lines, each listed URL should return 200 without redirecting, and each version's canonical should point at itself.

Google's page lists third-party tools for generating and testing hreflang, noting that it does not maintain or check them. For a quick check of a live page along with the rest of its search setup, run the free scan on LaunchScaler. It needs only your URL and no account, and its free search checks flag hreflang annotations without reciprocal return tags, hreflang targets that redirect or do not return 200, and invalid HTML in the <head> that drops the canonical, robots and hreflang tags below it, among 156 checks across 6 of its 7 categories.