If your site exists in several languages, or in versions for different countries, hreflang tells search engines which version to show to which users. Without it, a Spanish speaker may land on your English page, or your UK and US pages may compete with each other. Hreflang doesn’t boost rankings by itself: it makes sure the right version ranks for each audience.
The basic annotation
Each page lists all its language versions, including itself:
<link rel="alternate" hreflang="en" href="https://example.com/pricing/">
<link rel="alternate" hreflang="es" href="https://example.com/es/pricing/">
<link rel="alternate" hreflang="ja" href="https://example.com/ja/pricing/">
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing/">The same block appears on the English, Spanish and Japanese pages.
Language and region codes
- Language: ISO 639-1 (
en,es,zh,pt). - Optional region: ISO 3166-1 alpha-2 (
en-GB,en-US,pt-BR,es-MX). - Scripts for Chinese:
zh-Hans/zh-Hant, or region forms likezh-CN/zh-TW.
Region alone is invalid (hreflang="uk" means Ukrainian, not the United Kingdom, and en-UK is wrong: it’s en-GB).
Use region codes only when the content really differs by country (currency, spelling, shipping, legal terms). Otherwise plain language codes are simpler.
x-default
x-default is the fallback for users whose language doesn’t match any version, typically your main language page or a language selector. It’s optional, but recommended.
Rules that break hreflang when ignored
- Return links: if page A lists page B, page B must list page A. One-way annotations are ignored.
- Self-reference: each page includes itself.
- Canonical alignment: each version’s canonical points to itself, not to the English page. Hreflang URLs must be the canonical, indexable 200 URLs. See canonical URLs.
- Absolute URLs with the correct protocol and host.
- Equivalent pages: link each page to its translation, not to the other language’s home page.
Three ways to implement
| Method | Best for |
|---|---|
HTML <link> tags in <head> |
Most sites; easy to generate in templates |
XML sitemap xhtml:link entries |
Large sites; keeps HTML light |
HTTP Link headers |
PDFs and other non-HTML files |
Sitemap example:
<url>
<loc>https://example.com/pricing/</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/pricing/"/>
<xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/pricing/"/>
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing/"/>
</url>(The urlset element needs xmlns:xhtml="http://www.w3.org/1999/xhtml".) See XML sitemaps. Pick one method, as mixing them makes errors harder to find.
URL structures
| Structure | Example | Notes |
|---|---|---|
| Subdirectories | example.com/es/ |
Easiest; shares domain authority; one server |
| Subdomains | es.example.com |
More separation; slightly more setup |
| Country domains (ccTLDs) | example.es |
Strong country signal; most expensive to run |
| Parameters | ?lang=es |
Not recommended |
Subdirectories are the usual choice for a single business serving several languages from one VPS.
Partial translations
If only some pages are translated, add hreflang only for pages that exist in each language. Don’t point to English pages labeled as Spanish. Untranslated sections simply have no es alternate.
Don’t auto-redirect by IP or language
Forcing users (and Googlebot, which mostly crawls from the US) to a version based on IP or Accept-Language can hide your other versions from search. Show a suggestion banner instead, remember the user’s choice, and let hreflang do the search-side work.
Server location
Hreflang and content matter much more than where the server is. For speed, host near your largest audience and use a CDN for the rest. See choosing a VPS location and CDN for websites.
Common errors
- Missing return links (the most common).
- Wrong codes (
en-UK,jpinstead ofja,cninstead ofzh). - Hreflang pointing to redirected, noindexed or non-canonical URLs.
- All language versions canonicalized to one language.
- Annotations only on the home page.
- Machine-translated pages that are thin or low quality. Hreflang can’t fix quality.
Testing
- Crawl the site with an SEO crawler that validates hreflang (return links, codes, status).
- Check pages with
curl -s URL | grep hreflang. - Search Console shows which URL Google picked as canonical for each version (URL Inspection).
Quick reference
| Item | Rule |
|---|---|
| Codes | language or language-REGION (en-GB) |
| Each page | Lists all versions + itself |
| Links | Must be reciprocal |
| Fallback | x-default |
| Canonical | Self, per language |
| Methods | HTML head, sitemap, or HTTP header |
Related: technical SEO on your own server and website migration SEO.