hreflang tags: return tags, x-default and the errors that void them
hreflang tells Google which URL serves which language. Every page must list itself and each alternate with valid codes, or Google ignores the pair.
LLaunchScaler·Published ·8 min read
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: elements in each page's , a HTTP header, or 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.
Questions, answered
What people ask about this
01
What does hreflang mean?
hreflang is an attribute on a link rel=alternate annotation that tells Google a URL is the version of a page for a specific language, or language and region. Google uses it to show searchers the version that matches their language settings.
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.
Value
Valid?
Why
en
Yes
English, any region
en-GB
Yes
English for the United Kingdom
en-UK
No effect
UK is a reserved code, not the ISO code for the United Kingdom; Google says it has no effect
de-BE, fr-BE, nl-BE
Yes
German, French and Dutch for users in Belgium
be
Not what you meant
be is the language code for Belarusian, not Belgium
es-419
No
Google says codes outside the two standards, such as es-419, are not supported
zh-Hant, zh-Hans-US
Yes
Scripts can be given with ISO 15924, with an optional region
GB
No
A region without a language is invalid
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:
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.
Error
What happens
Fix
Missing return link
Google ignores the pair
Generate the full set from one list and output it on every version
Invalid or reserved code (en-UK, es-419, region alone)
That part of the annotation is ignored
Use ISO 639-1 plus an optional ISO 3166-1 Alpha 2 code
Alternate URL redirects, returns 404, or is http://
The pair points at a URL that is not the page Google indexes
List the final https:// URL that returns 200
Every language version canonicalises to the English page
Google keeps only the English page
Give each language version a self-referencing canonical
Relative or protocol-less URLs
The annotation is invalid
Use fully qualified URLs
Tags outside the <head>
They are not read as head annotations
Fix the invalid element that closes the head early
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.
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.
x-default is the reserved value for the page to show when no other language or region matches the searcher's browser settings. Google says it was designed for language selector pages, though you can point it at any fallback page.
03
What are hreflang return tags?
If page A lists page B as an alternate, page B must list page A back. Google ignores a pair that does not point both ways, so every version of a page carries the same full set of annotations, including one for itself.
04
Is it en-GB or en-UK in hreflang?
en-GB. The region part must be an ISO 3166-1 Alpha 2 code, and GB is the code for the United Kingdom. Google says reserved codes such as UK, EU and UN have no effect in hreflang annotations.
05
Do I need hreflang if my site is only in English?
Not for a single-language site with one version of each page. hreflang is for sites that have the same page in more than one language, or regional variants such as separate US and UK pages.
The Strict-Transport-Security value for testing, production and preload, what the preload list requires, and why removal from it takes weeks to months.
A Next.js hydration error means server HTML and the first client render differ, so React rebuilds the tree. The causes, the fix for each, and the SEO cost.
