Hreflang: Syntax, Return Tags and x-default

Hreflang is an HTML attribute, used as <link rel="alternate" hreflang="de" href="...">, that tells search engines which URLs are language or regional versions of the same page, so each searcher is shown the right one. It does not translate anything, detect language or boost rankings. It swaps URLs: when a German speaker searches, Google can show your German page instead of your English one.

This guide is for teams running a site in more than one language or for more than one country. It covers when you need hreflang, the syntax and valid codes, return tags, x-default, the three implementation methods, how hreflang interacts with canonical tags, the errors that break it, and the international SEO basics around it.

On this page

• When do you need hreflang?
• Hreflang syntax and valid codes
• Return tags: why every link must point both ways
• What does x-default do?
• Three ways to implement hreflang
• Hreflang and canonical tags
• Common hreflang errors
• International SEO basics beyond hreflang
• Getting hreflang right on a multilingual site

When do you need hreflang?

You need hreflang when the same content exists at different URLs for different languages or regions. Google’s guide to localized versions of your pages names three situations:

• Translated templates only. The main content stays in one language but the navigation and footer are translated, which is common on forums and other user-generated sites.
• Small regional variations in one language. English pages for the US, the UK and Ireland that differ in prices, spelling or shipping details.
• Full translations. German and English versions of every page.

Google adds that it may find alternate versions without any annotation, “but it is usually best for you to explicitly indicate your language- or region-specific pages”. It also clarifies what hreflang is not: Google “doesn’t use hreflang or the HTML lang attribute to detect the language of a page; instead, we use algorithms”. Hreflang declares relationships between URLs. The page’s visible text still has to be in the language you claim.

Most sites never need it. The 2022 Web Almanac found hreflang on 9.6% of sites on desktop and 8.9% on mobile.

Hreflang syntax and valid codes

An hreflang value is a language code, optionally followed by a region code, separated by a hyphen. The language must be ISO 639-1 (two letters, such as de), and the region, if used, must be ISO 3166-1 Alpha 2 (such as CH). Google’s documentation lists the rules that trip people up:

• The language always comes first. You can’t target a country alone. be is Belarusian, not Belgium; German speakers in Belgium are de-BE.
• Only official codes work. Google says es-419 (Latin American Spanish) isn’t supported, and reserved codes such as UK, EU and UN have no effect. The UK is GB.
• Case doesn’t matter. Google accepts en-gb and en-GB, though uppercase regions follow the ISO convention.
• Scripts are allowed. zh-Hant and zh-Hans specify Traditional and Simplified Chinese, and zh-Hans-US adds a region.

In the same Almanac, plain en was the most popular value, at 5.4% usage on desktop and 4.7% on mobile, followed by x-default, then French, German and Spanish. The diagram breaks one value down and sorts common codes into valid and invalid.

Scroll the diagram sideways to see all of it.

The HTML form goes in the <head> of every version, one link per version including the page itself. The set is identical on every page:

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

All URLs must be fully qualified, including https://. Google’s example rejects //example.com/foo and /foo.

Return tags: why every link must point both ways

The annotations only work when they are confirmed from both ends. Google’s rule is short: “If two pages don’t both point to each other, the tags will be ignored.” The reason is defensive. Without it, anyone could publish a page claiming to be the French version of yours.

Each version must also list itself. So on a site with English, German and French versions, every page carries the same three annotations, plus x-default if you use one. The diagram shows a complete cluster and what happens when one return link is missing.

Scroll the diagram sideways to see all of it.

Google allows some slack on large sites. If a complete set is hard to maintain, you can omit some languages on some pages, and Google “will still process the ones that point to each other”. It advises prioritizing links between new language versions and your original, strongest version over links between the new versions themselves.

What does x-default do?

x-default names the fallback page for searchers whose language settings match none of your listed versions. Google says it “was designed for language selector pages and so it will work best with those”, though any page can take the role. It needs no language code of its own, because by definition it serves unmatched users.

Two practical patterns work well. On a site with a country selector at the root, point x-default at the selector. On a site without one, point it at the version most likely to serve an international visitor, usually the generic English page.

Three ways to implement hreflang

Google supports three methods and treats them as equivalent: link elements in the HTML head, an HTTP Link header, and xhtml:link entries in an XML sitemap. Its advice is to pick one. Using all three brings “no benefit in Search” and is “much harder to manage”.

The sitemap method has one advantage the others lack: the annotations live in one file generated from one data source, so return links are consistent by construction. Google also notes that the child xhtml:link entries don’t count toward the 50,000 URL limit. Format and limits are covered in our guide to the XML sitemap.

Hreflang and canonical tags

Each language version should carry a canonical tag pointing to itself, and every hreflang target should be a canonical URL. Pointing the canonical of your German page at the English page tells Google the German page is a copy, which cancels the hreflang relationship. For how canonicals work in general, see our guide to the canonical tag.

Two related rules from Google’s documentation settle most confusion:

• Translations are not duplicates. Localized versions “are only considered duplicates if the main content of the page remains untranslated”. A proper German translation needs no canonical to the English original, and our guide to duplicate content SEO covers the cases that do count.
• Same-language regional copies are duplicates. If example.de/ and example.com/de/ both show similar German content, Google’s multi-regional guidance says to pick a preferred version and use both rel="canonical" and hreflang.

Google’s own systems appear to check canonical status during hreflang processing. The leaked Google API documentation, more than 2,500 pages of it by SparkToro’s count, analyzed by iPullRank in May 2024, includes a module for validating localized clusters with fields such as IndexingDupsLocalizedLocalizedClusterTargetLinkTargetDocData.isCanonical and IndexingDupsLocalizedLocalizedClusterTargetLinkTargetDocData.contentLanguage, the detected on-page language. Google stores these attributes; the leak does not show how much they are weighted. They are consistent with the public advice: target canonical URLs, and make sure the page’s visible language matches the code.

Common hreflang errors

These annotations break more often than they work. When Ahrefs studied hreflang across 374,756 domains, it found that 67% of implementations had issues. Google’s troubleshooting section names the three most common mistakes, and audits turn up the rest:

1. Missing return links. Page A names page B, but page B doesn’t name A. The most common failure, and the one most likely to be caused by publishing a translation before updating the original.
2. Wrong language codes. Regions used as languages, such as be for Belgium, which Google points out is actually the code for Belarusian.
3. Wrong region codes. en-UK instead of en-GB, or unofficial codes such as es-419.
4. Targets that aren’t canonical, live pages. Hreflang pointing at URLs that redirect, return 404, carry noindex or canonicalize elsewhere.
5. Relative URLs. Google requires fully qualified URLs including the protocol.
6. Tags outside the head. Google requires the links inside a well-formed <head>. Invalid elements placed in the head can push them into the body, where they are missed, so Google suggests running rendered code through an HTML validator if in doubt.
7. Missing self-reference. Each version must list itself as well as the others.
8. Language that doesn’t match the code. A page tagged fr whose main content is still English.

Hand-maintained tags drift. The durable fix is to generate the annotations from one table of URL equivalents, at build time or from the CMS, and to check it after every release with a crawler that validates return links.

International SEO basics beyond hreflang

Hreflang is one part of international SEO. The other decisions happen earlier, often at the web design stage, and matter as much. Google’s multi-regional guidance covers the essentials:

• Use separate URLs per language. Google recommends distinct URLs rather than switching language by cookie or browser setting, and warns that Googlebot usually crawls from the US without an Accept-Language header, so content varied by those signals may never be seen.
• Don’t auto-redirect by guessed language or IP. Google advises against it, because it can stop users and crawlers reaching every version. Link to the other versions instead.
• Choose a URL structure deliberately. Country-code domains such as example.de give the clearest geotargeting but cost more and target one country each. Subdirectories such as example.com/de/ are easy to run on one host. Subdomains sit in between. URL parameters such as ?loc=de are not recommended.
• Ignore geo meta tags. Google says it ignores locational meta tags such as geo.position.
• Keep one language per page. Google determines language from visible content, and side-by-side translations muddy it.

The figure below lists the signals Google says it uses to decide which locale a page targets, and the ones it ignores.

Scroll the diagram sideways to see all of it.

If you’re restructuring URLs to add languages, treat it as a migration and follow our website migration SEO checklist, with redirects mapped before launch.

Getting hreflang right on a multilingual site

The system is simple in principle and fragile in practice, because it is a set of promises every page has to keep about every other page. The sites that get it right don’t have better SEO instincts. They generate the annotations from one source of truth, target only canonical 200-status URLs, and test return links automatically after every deploy.

Check your current state in Search Console (our Google Search Console guide shows where) and with a crawler that reports missing return tags, then work through the error list above. For the broader list of checks a multilingual site needs, see our technical SEO checklist for AI search. If you’re planning a new multilingual build or rebuilding one that has drifted, our web development service builds hreflang, canonicals and localized URL structures into the templates so they stay correct as content grows.