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;GBis invalid,en-GBis 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.
| Method | How | Best for |
|---|---|---|
HTML <link> elements in <head> | One <link rel="alternate" hreflang="code" href="url" /> per version, on every version | Sites with a manageable number of versions where the template can render the set |
| HTTP headers | A Link: header listing the alternates | Non-HTML files such as PDFs |
| XML sitemap | Each <url> entry lists <xhtml:link rel="alternate" hreflang="code" href="url" /> for every version | Large sites; keeps page HTML small; easier to generate from a database |
The sitemapA file listing the URLs a site wants search engines to discover and crawl. 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
- Every version lists every version, including itself. A page's annotation set is the complete group. The self-reference is required.
- Annotations must be reciprocal. If page A names page B as its
fralternate, 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. - URLs must be absolute and final: the indexable URL, with protocol and host, not a redirect, not a URL that canonicalises elsewhere.
- Each version is its own canonical (Canonical TagTells search engines the preferred URL.). 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-CApage canonical to itself, listed in the group asfr-CA. - One
x-defaultper group, pointing at the fallback page, which is itself in the group. - Only indexable pages belong in a group. A
noindexversion or a blocked one breaks the set. - 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:
- 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.
- 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. - 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.
- 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.
- Monitoring: Search Console (GSCGoogle's search performance and indexing tool.) 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.
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
| Report | Meaning | Fix |
|---|---|---|
| No return tags | Page A lists B, B does not list A | Make the generator emit the full group on every member |
| Unknown language code | Invalid or non-ISO code | Correct the code map; en-GB not en-UK |
| Missing self-reference | Group omits the page itself | Emit self in every group |
| hreflang pointing to a non-canonical URL | Target canonicalises elsewhere or redirects | Point 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 edition | Self-canonical per locale |
| Conflicting hreflang across methods | HTML and sitemap disagree | Use 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.
