Hreflang: The Complete Guide, With Data From 78 Major Websites
What hreflang is, valid codes, three ways to implement it, canonical rules, common errors and a 10-minute test, with data from 78 major websites.
Hreflang is an annotation that tells search engines which language, and optionally which country, a page is written for, and where the other versions of that page live. Google uses it to show searchers the version that matches their language and region. It does not boost rankings. It swaps the right version into the results.
This guide covers the syntax, the three ways to implement it, the rules that break most setups, the interplay with canonical tags and a test you can run on your own site in 10 minutes. It also includes data from our audit of 123 major websites, where 78 readable homepages show how large brands handle it in practice.
What hreflang does and what it does not do
A site with a French page and an English page about the same product has a problem: a search engine sees two pages and must decide which one to show to whom. Hreflang answers that question. Each page declares its siblings, and the engine picks the one that fits the searcher.
Three limits are worth knowing from the start. Hreflang is a hint, not a command, so a search engine can still show another version. It does not raise a page in the rankings: it only affects which of your versions appears for which audience. And it does not translate anything. The versions must exist, and they must be good.
Valid hreflang codes
A value is a language code in ISO 639-1, optionally followed by a region code in ISO 3166-1 alpha-2, joined by a hyphen. A region alone is never valid. The special value x-default marks the fallback page.
Value | Meaning | Use it when |
|---|---|---|
| English, any country | One English version serves everyone |
| English for the United Kingdom | Pricing, spelling or legal text differ from |
| French for Belgium | Belgian pricing, delivery or terms |
| Dutch for Belgium | Flemish audience with local content |
| Spanish for Mexico | Mexican pesos, local shipping |
| Portuguese for Brazil | Brazilian Portuguese, not European |
| No language matches | Language selector or global page |
Two details trip people up. The language comes first and the region second, so fr-BE is right and be-fr is not. And the region must be an ISO country code: the United Kingdom is GB, not UK.
Three ways to implement hreflang
Google documents three equivalent methods. Pick one and use it everywhere.
1. Link tags in the HTML head
This is the default for ordinary web pages. Put one tag per version in the head of every version, including a tag that points to the page itself:
<link rel="alternate" hreflang="fr-BE" href="https://example.com/fr-be/" />
A page with three versions and a fallback carries four of these tags, and the other versions carry the same four. Head tags are easy to review with view-source, which makes them the best choice for small and mid-sized sites.
2. HTTP header for non-HTML files
A PDF has no head to put tags in. For these files the server sends the annotation in the response header:
Link: <https://example.com/guide-fr.pdf>; rel="alternate"; hreflang="fr", <https://example.com/guide-en.pdf>; rel="alternate"; hreflang="en"
The same rules apply: list every version, the file itself included. You configure this in the web server or the CDN, so check the headers with a tool such as curl -I after each change.
3. XML sitemap
On large sites, a sitemap keeps the annotations out of every page and in one place. Declare the xhtml namespace on the urlset element, then add an entry like this inside each url:
<xhtml:link rel="alternate" hreflang="nl-BE" href="https://example.com/nl-be/" />
Every url entry lists all its alternates, itself included. A sitemap suits sites with thousands of pages and several languages, because a template change does not touch the page weight. The cost is visibility: you cannot see the annotations by viewing a page.
The rules that matter
- Self-reference. Each page lists itself among its alternates.
- Return links. If page A points to page B, page B must point back to A. Without the return link, the annotation can be ignored.
- Absolute URLs. Use the full address with protocol and host. Relative paths are not valid.
- One URL per language and region. Two pages cannot claim
fr-BE, and one URL cannot appear under two values. - Indexable targets. Every URL must return 200, carry no noindex and not redirect.
- x-default. Name a fallback for visitors your languages do not cover, usually a selector or the main global page.
Hreflang and canonical tags
The two tags answer different questions. Canonical says which URL is the preferred copy of a page. Hreflang says which pages are the language and region variants of one another.
Each language version must canonicalize to itself. The French page carries a canonical tag pointing to the French URL, and the English page points to the English URL. If the French page canonicalizes to the English one, you tell the search engine that the French page is a duplicate and should not be indexed, which cancels the hreflang annotation you added. The URLs you list in hreflang should be the canonical URLs, and nothing else.
Common hreflang errors
Invalid codes
Typos in the value are the most common failure and the quietest, because nothing reports them. Examples we see: es-CE (no such region), in-ID (in is a retired code, Indonesian is id), es-SP (Spain is ES), en-UK (use GB) and english (use en). A search engine may skip a value it cannot parse.
Relative URLs
A tag with href="/fr/" is not valid. The address needs https:// and the host, every time.
Missing return links
The English page lists the French one, but the French page does not list the English one. This happens when a new language is added to one template and not the others, or when a page exists in two languages and not in a third.
Targets that redirect or block indexing
An alternate that returns a 301, a 404 or a noindex tag cannot be shown in results, so the annotation points nowhere. Redirects appear after a migration, when old URLs stay in the template.
Mixed methods that disagree
Some sites declare hreflang in the head and in the sitemap, with different lists. When the two sources conflict, you cannot predict which one a search engine will follow. Choose one method, or keep both generated from the same data.
How to test hreflang on your own site in 10 minutes
- Minute 1 to 2. Open your homepage, view the source and search for
hreflang. Note every value. - Minute 3 to 4. Check each code against the ISO lists. Look for region-only values,
UK, and codes that are not two letters. - Minute 5 to 6. Check that every href starts with
https://and includes your domain. - Minute 7 to 8. Run
curl -sIon each alternate URL. You want a 200 with no redirect and no noindex. - Minute 9. Open one alternate and confirm it lists the first page back and itself.
- Minute 10. Compare the canonical tag of each version with its own URL.
Repeat on one deep page, such as a product or an article, because templates for deep pages often differ from the homepage. If you use a sitemap, open it and spot-check three entries the same way.
What 78 major websites do
On 25 October 2026 we read the homepages of major brand sites and recorded how they declare language versions. 78 homepages were readable. The full method and its limits are in the audit post.
- 45 of 78 (58%) declare hreflang for two or more languages.
- 31 declare none.
- Of the 45, 31 (69%) include
x-defaultand 14 (31%) do not. - One site published three invalid values.
- One site used relative URLs.
- 30 of 78 (38%) redirect the bare domain to a locale URL.
Large brands use hreflang more often than not, and the errors that remain are the basic ones: a missing fallback, malformed codes, relative paths. None of this needs advanced tooling to fix. It needs someone to look at the source.
At Globaprom we build software i18n-first, with language routing, hreflang and sitemaps generated from one source of truth. If you are planning that for your product, start with software internationalization explained and our multilingual software page.
Frequently Asked Questions
Does Google use hreflang for ranking?
No. Google uses it to swap the right language or regional version into search results. It does not boost a page in the rankings. If your French page ranks poorly, hreflang will not fix it, but it will stop an English page from standing in for it.
Does Bing use hreflang?
Bing says it relies mainly on the html lang attribute and content-language signals to understand a page. Set the lang attribute correctly on every version whatever else you do, since it costs nothing and helps in every case.
Do I need hreflang for one language with several countries?
Use it when the versions differ in a way a visitor would notice, such as currency, delivery, spelling or legal terms. A page for en-GB and another for en-US is the classic case. If the pages are identical, a single en version is simpler.
Can hreflang be in both the head and the sitemap?
It can, but it should not be needed. Google asks you to choose one method. If you use two, generate them from the same data so they always match, because conflicting lists make the result unpredictable.
Which method should I choose?
Head tags for small and mid-sized sites, the HTTP header for PDFs and other non-HTML files, and the sitemap for large catalogs. Whichever you pick, follow the same rules: self-reference, return links, absolute URLs and a fallback.
Keep reading
Need software that speaks every market from day one?
Tell us what you need built. We reply with a fixed scope, a fixed price, and a delivery date measured in weeks.