Hreflang Explained: How to Set Up Language and Region Versions
When hreflang is worth adding, the exact syntax for HTML, HTTP headers and sitemaps, and how codes, x-default and return links work. Plus how hreflang interacts with canonicals and what Bing looks at instead.
Hreflang is an annotation that tells Google which language or regional version of a page to show each searcher, for example your en-US page to Americans and your en-GB page to Britons. You need it when the same content exists in several languages or regional variants; a single-language site doesn’t. It only works when every version lists all the others, including itself, so most hreflang problems are bookkeeping problems.
Key takeaways
- Use hreflang for equivalent pages in different languages, or in the same language for different regions.
- Codes are an ISO 639-1 language, optionally followed by an ISO 3166-1 alpha-2 region:
en,en-GB,es-MX. A region alone is invalid, and the UK isGB. - Every page must list itself and every alternate, and every alternate must link back. One-way annotations are ignored.
- Each version keeps a self-referencing canonical. Never canonicalize a translation to the original language.
- Google ignores the
langattribute for language detection, but Bing has long used it and the content-language meta tag, so set those too.
When you need hreflang (and when you don’t)
Add hreflang when you have:
- Translations of the same page, such as English, French and Arabic versions of a product page.
- Regional variants in one language that differ in currency, prices, spelling, shipping or legal terms, such as
en-US,en-GBanden-AU. - Partly translated sites where only the template is localized but the main content is the same. Hreflang is allowed here, though fully translated content serves users better.
You don’t need it for a site in one language, or for country sites whose pages have no equivalents elsewhere. Also keep expectations realistic: hreflang is a signal, not a directive. It helps Google swap in the right URL for a searcher; it doesn’t redirect users, pass ranking strength between versions or make a weak translation rank.
Choose a URL structure first
Hreflang works with any structure, but the structure decides how much work it is. Google describes the trade-offs in its guide to multi-regional sites:
| Structure | Example | Good for | Watch out for |
|---|---|---|---|
| Subfolders | example.com/fr/ | Most sites: one domain, one hosting setup, shared authority | Keep every language folder on the same templates |
| Country domains (ccTLDs) | example.fr | Strong country signal, separate local brands | Several domains to build up and maintain |
| Subdomains | fr.example.com | Separate platforms per market | More setup; often treated more like separate sites |
| URL parameters | example.com/?lang=fr | Nothing, really | Not recommended by Google; hard to crawl and annotate |
Language and region codes
Google’s localized versions documentation accepts an ISO 639-1 language code, optionally followed by a hyphen and an ISO 3166-1 alpha-2 region code. You can also give a script, such as zh-Hant for Traditional Chinese. Codes aren’t case-sensitive, but the convention is lowercase language and uppercase region.
| Wrong | Right | Why |
|---|---|---|
en-UK | en-GB | The ISO code for the United Kingdom is GB |
us | en-US | A region alone isn’t valid; the language is required |
en_US | en-US | Use a hyphen, not an underscore |
es-EU | es-ES or es | EU is a reserved code with no effect in Search |
ar-AR | ar, ar-MA, ar-SA | AR is Argentina, not “Arabic world” |
es-419 | es or individual countries | 419 (Latin America) is valid BCP 47, but Google documents only two-letter region codes |
A useful default: use language-only codes (fr, es, ar) unless you genuinely have different versions per country. A single es page serves every Spanish speaker; you only need es-MX and es-ES if those pages differ.
Three ways to implement hreflang
All three methods follow the same rules. Pick one per page type and stick to it; mixing methods is allowed, but conflicting annotations are a common source of errors.
1. Link elements in the HTML head
The simplest option for most sites. Every version carries the same block:
<link rel="alternate" hreflang="en" href="https://example.com/en/pricing/">
<link rel="alternate" hreflang="fr" href="https://example.com/fr/tarifs/">
<link rel="alternate" hreflang="es" href="https://example.com/es/precios/">
<link rel="alternate" hreflang="x-default" href="https://example.com/en/pricing/">2. HTTP Link headers
Use these for non-HTML files such as PDFs, where you can’t add head tags. The whole header goes on one line, with alternates separated by commas:
Link: <https://example.com/en/guide.pdf>; rel="alternate"; hreflang="en", <https://example.com/fr/guide.pdf>; rel="alternate"; hreflang="fr"3. XML sitemap
Best for large sites, because it keeps annotations out of page templates. Each <url> entry lists every alternate, including itself:
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://example.com/en/pricing/</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing/"/>
<xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/tarifs/"/>
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/pricing/"/>
</url>
<url>
<loc>https://example.com/fr/tarifs/</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing/"/>
<xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/tarifs/"/>
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/pricing/"/>
</url>
</urlset>x-default: the fallback version
The reserved value x-default tells Google which page to show when none of your languages or regions match the searcher. Point it at your language selector, or at the version you’d want an unmatched visitor to see, usually the international English page. If your home page detects language and redirects, the redirecting URL is the natural x-default.
x-default is optional, but it’s worth adding on any site that targets more than two or three markets.
Return links and self-references
This is where most implementations break. Google’s rule: if page A lists page B as an alternate, page B must list page A. If the two pages don’t point to each other, Google ignores the annotations. Each page must also include itself in its own set.
The reliable way to get this right is to generate the hreflang block from one map of equivalent URLs, so every page in a group prints the identical list. Building it by hand page by page almost guarantees that someone forgets a language when a page is added, renamed or deleted.
Worked example: four versions of one page
Say a shop sells in the US, the UK, France and French-speaking Canada. The product page exists in four versions, and the US page doubles as the fallback. Each of the four pages prints exactly this block, nothing more and nothing less:
<link rel="alternate" hreflang="en-US" href="https://example.com/us/kettle/">
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/kettle/">
<link rel="alternate" hreflang="fr-FR" href="https://example.com/fr/bouilloire/">
<link rel="alternate" hreflang="fr-CA" href="https://example.com/ca-fr/bouilloire/">
<link rel="alternate" hreflang="x-default" href="https://example.com/us/kettle/">A French speaker in Belgium matches none of the regional codes exactly. If you want them to land on the France page rather than the x-default, add a language-only line, hreflang="fr", pointing to /fr/bouilloire/, on all four pages. Language-only codes act as a catch-all for every region you haven’t listed.
How hreflang and canonical tags interact
- Each language version gets a self-referencing canonical. If
/fr/tarifs/has a canonical pointing to/en/pricing/, you’re telling Google the French page is a duplicate to drop, and the hreflang conflicts with that. - Hreflang URLs must be canonical and indexable. Every listed URL should return
200, carry nonoindexand be the exact canonical URL, including protocol, host and trailing slash. - Use absolute URLs. Relative paths in hreflang are a frequent cause of silent failures.
- Near-identical regional pages may be clustered. If your
en-USanden-GBpages are identical apart from one word, Google may pick one as canonical. Hreflang can still show the right URL in each country, but genuine localization (currency, spelling, shipping) makes the variants stronger.
Bing and other search engines
Google and Yandex support hreflang. Bing has historically said it relies mainly on other signals to work out a page’s language and region, especially the content-language meta tag and the HTML lang attribute, along with the domain and server location. Google, on the other hand, says it doesn’t use either of those to detect language. Adding both is cheap and covers both engines:
<html lang="fr-CA">
<head>
<meta http-equiv="content-language" content="fr-ca">
...The lang attribute also helps screen readers pronounce your text correctly, so it’s worth setting on every page regardless of SEO (see MDN’s lang reference).
Common hreflang mistakes
- Missing return links, often after a new language is launched on only part of the site.
- Invalid codes such as
en-UK, underscores or region-only values. - Alternates that redirect, return 404 or are noindexed.
- Canonicals that point across languages.
- Pointing every alternate at the home page instead of the equivalent page.
- Forced IP-based redirects. Googlebot crawls mostly from US addresses; if it’s always redirected to the US version, it may never see the others. Let visitors choose, or suggest a version with a banner instead.
- A broken
<head>. If a script injects an element that isn’t allowed in the head, such as an<img>or<div>, parsers end the head early and hreflang tags after it can be missed. - HTML and sitemap annotations that disagree after one of them is updated and the other isn’t.
Check your hreflang setup
Search Console’s old International Targeting report was retired in 2022, so you need another way to audit annotations. The hreflang checker lists the alternates a page declares in its HTML and HTTP headers, validates the language and region codes, checks x-default and self-reference, and fetches each alternate (up to 10) to verify return links and canonicals. If your annotations live in the sitemap, the sitemap validator checks hreflang alternates there. To confirm each version’s canonical points to itself, use the canonical checker. For the bigger picture, international setup is one section of our technical SEO checklist, and the hreflang glossary entry is a short definition to share with translators and developers.