Skip to content
Faisal Mahmud TusherDigital marketing, SEO & analytics
with Faisal Tusher

SEO › International SEO

hreflang, Explained

hreflang explained: codes, the three places to declare it, reciprocity and x-default, canonical interaction, generation at scale and fixing errors.
Guideadvanced8 min readUpdated

What hreflang does

Google's documentation describes hreflang as a way to tell it about localised versions of a page so that search can point users to the most appropriate version by language or region. It applies when a site has:

  • the same content in different languages;
  • the same language with regional variations (prices, spellings, availability);
  • partially translated pages, where the template is localised but the main content is not.

What it does not do: it does not translate, it does not geotarget a whole site (that is the URL structure in the international hub), it does not make a page rank, and it does not consolidate signals between versions the way a canonical does. Google states it is a signal rather than a directive and that other signals may override it.

Codes

Each annotation carries a language code and, optionally, a region code:

  • Language: ISO 639-1 two-letter codes (en, fr, de, pt). Google documents that it does not support deriving the language from the region alone.
  • Region: optional, ISO 3166-1 alpha-2 country codes appended after a hyphen (en-GB, en-AU, pt-BR, fr-CA). Regions cannot stand alone; GB is invalid, en-GB is valid.
  • Script: an optional ISO 15924 script subtag is supported (zh-Hant, zh-Hans).
  • x-default: a reserved value for the page to show when no language or region matches — typically a language-selection page or the primary edition.

Invalid codes (en-UK, uk, english, a region alone) are the most common syntactic error; Search Console reports them.

Where to declare it

Google documents three methods; use one, consistently, for the whole site.

MethodHowBest for
HTML <link> elements in <head>One <link rel="alternate" hreflang="code" href="url" /> per version, on every versionSites with a manageable number of versions where the template can render the set
HTTP headersA Link: header listing the alternatesNon-HTML files such as PDFs
XML sitemapEach <url> entry lists <xhtml:link rel="alternate" hreflang="code" href="url" /> for every versionLarge sites; keeps page HTML small; easier to generate from a database

The sitemap method scales best: one generator reads the content database and emits the full set for each URL, and validation is a script over one file. Mixing methods invites disagreement between them.

The rules

  1. Every version lists every version, including itself. A page's annotation set is the complete group. The self-reference is required.
  2. Annotations must be reciprocal. If page A names page B as its fr alternate, page B must name page A as its alternate too, or Google reports a missing return tag and may ignore the pair. One-directional annotations are the single largest source of hreflang failure.
  3. URLs must be absolute and final: the indexable URL, with protocol and host, not a redirect, not a URL that canonicalises elsewhere.
  4. Each version is its own canonical (Canonical Tag). A localised page whose canonical points at the primary edition tells the engine it is a duplicate, which removes it from the group. The canonical and hreflang must agree: fr-CA page canonical to itself, listed in the group as fr-CA.
  5. One x-default per group, pointing at the fallback page, which is itself in the group.
  6. Only indexable pages belong in a group. A noindex version or a blocked one breaks the set.
  7. Groups are per page, not per site. A product that exists in three markets has a three-member group; a page that exists in one market has none.

Interaction with canonicals and redirects

The canonical says "this URL represents this content"; hreflang says "these URLs are equivalents for different audiences". For them to coexist, every member of a group must be canonical to itself. The failure mode is a site that correctly canonicalises parameterised duplicates and then, by template inheritance, canonicalises every locale to the default locale — which quietly removes every other edition from the index while hreflang continues to point at them. The crawling and indexing guide covers canonical behaviour.

Redirects are the other trap: an href that redirects (an old URL, a trailing-slash variant, an HTTP version) is not the final URL, and Google documents that hreflang values must point at the page's actual address. After any migration, the hreflang set is regenerated, not redirected. The same applies when a single page is retired or replaced, and the guide to keeping localised content in step with the source removes it from every edition's alternates in one release.

Generating hreflang at scale

Hand-written hreflang does not survive the second product launch. The approach that holds:

  1. A locale map in the content system: for each canonical content item, the URL in each locale where it exists, and a flag for whether that locale version is live and indexable.
  2. A generator that, for each live item, emits the full group (all live locales plus x-default) in the sitemap or the template, reading only from the map.
  3. Rules for partial coverage: an item missing in a locale is simply absent from that group; the group does not point at a non-existent or redirected page.
  4. Validation on build: a script checks every group for reciprocity, self-reference, valid codes, absolute final URLs, canonical agreement and indexability, and fails the build on error.
  5. Monitoring: Search Console (GSC) reports hreflang issues under international targeting or page indexing, depending on the current interface; backlink and crawl tools report the same with more detail.

The international SEO expertise page includes a generator for the annotation set of one page; for a site, the generator belongs in the build.

Illustrative example — not a real result

A software company's four editions

A software company serves English for the United States, English for the United Kingdom, German, and Japanese, in subdirectories, with the US edition as the default. Its locale map lists each marketing page with the four URLs where they exist; the pricing page has all four, a regional compliance page exists only in de. The sitemap generator emits, for the pricing page, four alternates plus x-default pointing at the US page, on each of the four entries; for the compliance page, nothing, since it has no alternates. Build validation fails when a new Japanese page is published with a canonical inherited from the US template, and the template is fixed before deployment. Search Console's report for the site shows no return-tag errors after the first full recrawl, and searches in Germany for the product name show the German pricing page rather than the US one.

Search Console errors and fixes

ReportMeaningFix
No return tagsPage A lists B, B does not list AMake the generator emit the full group on every member
Unknown language codeInvalid or non-ISO codeCorrect the code map; en-GB not en-UK
Missing self-referenceGroup omits the page itselfEmit self in every group
hreflang pointing to a non-canonical URLTarget canonicalises elsewhere or redirectsPoint at the final canonical URL; fix the canonical
Alternate page with proper canonical tag (for a locale page)The locale page's canonical points at another editionSelf-canonical per locale
Conflicting hreflang across methodsHTML and sitemap disagreeUse one method

Partially translated and locale-adaptive sites

Two patterns need care. A site whose templates are localised but whose main content stays in one language (a product catalogue with translated navigation and untranslated descriptions) can still use hreflang, and Google's documentation specifically mentions this case; the regional pages remain near-duplicates in their main content, so they should differ in what matters to the market — prices, availability, shipping, local contact details — or the engine may fold them. A site that adapts content by the visitor's location or language settings without changing the URL (locale-adaptive pages) has no alternates to annotate; Google documents that it crawls such sites from a limited set of locations and may not see every variant, and recommends separate URLs per locale with hreflang instead.

Checking a single page by hand

Before trusting the generator, verify one page from each template manually: fetch the page and the sitemap entry; list every hreflang in the group; fetch each target and confirm it returns a successful status, has a self-referencing canonical, is not noindexed, and lists the original page in its own group with the matching code; confirm the x-default target is in the group; and check the codes against the ISO lists. Ten minutes per template catches the inheritance mistakes that the example above describes, before they reach thousands of pages.

What hreflang will not fix

  • Thin or identical editions. A regional page with nothing regional about it may be indexed and still not shown; Google folds near-duplicates regardless of annotation when it judges them the same.
  • Wrong structure. Parameters for locale, or locales mixed between subdomains and directories, confuse everything downstream.
  • Forced redirects by IP. The crawler cannot reach the other editions, and no annotation helps.
  • Missing local signals. Currency, addresses, local links and market-specific content are what make an edition the right answer in its market.

Before choosing how to structure market editions, read the subfolder versus subdomain comparison, which sets out how each option affects authority, maintenance and international targeting.

When the wrong edition still ranks in a market after annotations are in place, the troubleshooting page on Google showing the wrong country version checks canonicals, redirects and internal signals as well.

When annotations are being added for a market that is about to launch, the new market launch checklist puts the URL structure, the return links and the redirect check alongside the rest of the go-live work.

Common mistakes

  • One-directional annotations. The most frequent and the most damaging.
  • Canonical to the default edition. Every other edition vanishes.
  • Region without language. Invalid.
  • Relative URLs, redirecting URLs, HTTP URLs. Not final addresses.
  • Including noindex or blocked pages. The group breaks.
  • Hand maintenance. Any site with a release cadence needs generation and validation.
  • Expecting ranking gains. It routes; it does not rank.

The international hub covers the structural decisions that precede annotation; the site architecture guide covers how locale directories fit the hierarchy.

Frequently asked questions

Is hreflang a ranking signal?

No. Google documents it as a way to serve the correct language or regional URL to a searcher. It does not make a page rank; it decides which of a set of equivalent pages is shown once one of them would rank. A region with no hreflang can still rank; it may just show the wrong edition.

Do I need hreflang for a single-language site with one country?

No. hreflang is for pages that have alternates. A single edition has none. Adding self-referencing hreflang alone is harmless and pointless.

Does Bing use hreflang?

Bing's documentation describes using the content-language meta tag and other signals, with hreflang support more limited. Yandex supports hreflang. Implement for Google, and add the content-language declaration where other engines matter.

Terms used on this page

Frameworks

Where this page is used

Part of these learning paths

Also related

Sources

  1. Tell Google about localized versions of your page — Google Search Central
  2. Managing multi-regional and multilingual sites — Google Search Central

Related