hreflang implementation: tags, sitemaps, return links and common errors

hreflang is an annotation that tells search engines a page has equivalents in other languages or for other regions, and which version is meant for whom. A shop with English pages for the US and the UK, a German version and a French version can use hreflang to make sure a searcher in Germany sees the German page and a searcher in London sees the British one, with pounds and UK delivery information, instead of the American page.

It does not raise rankings. It helps the right version appear in place of the wrong one. And it is one of the most frequently broken pieces of technical SEO, because it depends on every page in a set agreeing with every other.

The rules in one paragraph

For each set of equivalent pages, every page lists every version in the set, including itself, with a language code (and optionally a region code) and an absolute URL. Every version must list the same set, so links are reciprocal ("return links"). Optionally, an x-default entry names the page for users who match none of the listed languages or regions. The URLs listed must be the canonical, indexable versions that return 200.

Codes: language first, region optional

• Language uses ISO 639-1 two-letter codes: en, de, fr, es, pt, vi, ja.
• Region is optional and uses ISO 3166-1 alpha-2 codes, after a hyphen: en-GB, en-US, es-MX, pt-BR, de-AT.
• A region alone is invalid. hreflang="gb" means nothing; it must be en-GB.
• Script variants can be expressed where needed, such as zh-Hans and zh-Hant for simplified and traditional Chinese.

Wrong	Right	Why
en-UK	en-GB	The country code for the United Kingdom is GB
en_US	en-US	Hyphen, not underscore
eu for "Europe"	One entry per country, or a language without region	eu is the language code for Basque
jp	ja	jp is the country; the language is ja
es-419	Use country codes such as es-MX, es-AR	Google does not support region groups like 419

Three ways to implement it

1. Link elements in the HTML head

<link rel="alternate" hreflang="en-us" href="https://example.com/us/boots/">
<link rel="alternate" hreflang="en-gb" href="https://example.com/uk/boots/">
<link rel="alternate" hreflang="de" href="https://example.com/de/stiefel/">
<link rel="alternate" hreflang="x-default" href="https://example.com/boots/">

The same block, with the same four entries, appears on all four pages. This is the most common method and the easiest to inspect. It adds weight to every page when there are many versions.

2. XML sitemap

Each <url> entry lists its alternates with xhtml:link elements. This keeps HTML light and is often easier for large sites to generate from a database, but harder to spot-check by viewing a page.

3. HTTP headers

For non-HTML files such as PDFs, the Link response header can carry the same annotations. Rarely needed for normal pages.

Use one method per set of pages. Mixing methods is allowed but makes conflicts likely.

x-default

x-default designates the fallback for users whose language and region match none of your versions. Common choices: a language selector page, the international English version, or the home page that redirects by location. It is optional but recommended, especially when the root page detects language automatically.

The errors that break it

• Missing self-reference. Each page must include itself in the list. Without it the set is incomplete.
• Missing return links. If the UK page points to the German page but the German page does not point back, search engines may ignore the pair.
• Relative URLs. href="/de/stiefel/" is not allowed; use the full URL with protocol and host.
• Pointing to non-canonical URLs. If the listed URL redirects, is noindexed, or has a canonical pointing elsewhere, the annotation conflicts with other signals. The canonical tags guide explains why canonicals and hreflang must agree: each regional page should be self-canonical.
• Canonicalising all versions to one. If the UK page canonicalises to the US page, you have told search engines the UK page is a duplicate, and hreflang cannot override that.
• Invalid codes, as in the table above.
• Pages that are not really equivalent. hreflang should link pages with the same content for different audiences. Linking the German home page to the English blog post confuses the set.
• Untranslated pages. A "German" page that is still in English is unlikely to be shown to German users, whatever the annotation says.

Same language, different regions

The trickiest sets are versions in one language for several countries: English for the US, UK, Australia and Canada, or Spanish for Spain and Mexico. Search engines may treat them as near-duplicates if they differ only in currency symbols. hreflang helps them understand the relationship, but each version is far more robust when it is genuinely localised: local spelling, prices in local currency with local taxes and shipping, local contact details, references to local regulations and holidays. If you have nothing different to say to Australian visitors than to British ones, consider whether you need separate versions at all; a single international English version is often the better choice.

Do not redirect users automatically

Many sites detect a visitor's location or browser language and redirect them to "their" version. This is risky. Search engine crawlers mostly come from a few locations, so automatic redirects can stop them from ever seeing other versions. Travellers, expats and people using VPNs get sent to the wrong place. A better pattern: serve the requested page as normal, and show a small banner suggesting the visitor's likely version with a link. Let people choose, and remember their choice in a cookie. If the root URL must route by location, mark it as x-default and keep every localised page reachable directly.

Checking your implementation

1. Spot-check one set by hand: open each version, view source, and confirm every page lists the same set including itself, with absolute URLs and valid codes.
2. Crawl the site with a crawler that validates hreflang. It will report missing return links, non-200 targets and conflicts with canonicals across the whole site.
3. Check the lang attribute on each page's <html> element matches the language of the content.
4. Run the SEO checker on your home page. It reports hreflang codes that are invalid or relative and a missing self-reference, as well as a missing lang attribute.
5. Check search results from the target countries (with a VPN or location settings) for your main queries and see which version appears.

Generating it reliably

hreflang breaks when people maintain it by hand. Generate it from a single source of truth: a table that maps each piece of content to its URL in each locale. When a page is added, removed or renamed in one language, the annotations update everywhere. For sites built on a CMS with multilingual plugins, check that the plugin outputs self-references and x-default, and that it updates other versions when one is unpublished.

When a page is removed in one language, remove it from the sets on all other versions in the same release; a set that points at a 404 is one of the most common errors crawlers report. Pages that exist in only some languages are fine: their sets simply contain fewer entries. Do not point a missing language to the home page of that language as a substitute; leave it out.

Where hreflang fits

hreflang is one part of serving an international audience. It depends on a sensible site structure (see international site structure), content that is genuinely localised (see localizing keywords), and correct canonicals. With those in place, hreflang does its narrow job well: putting the version each user can read and buy from in front of them.