Hreflang: The Complete Guide, and the Mistakes That Quietly Break It
Written by Armen Andonian · Published on 25 September 2026
Picture a hotel in the Eixample with an English site, a Spanish site and a Catalan site. A couple in Manchester searches for its name, and Google shows them the Spanish homepage. They squint at it for four seconds, hit back, and book through a comparison site that takes a fat commission.
Nothing on that hotel’s website is broken in the usual sense. Every page loads. The English version exists and is well written. Google simply was never told, in a way it trusts, which page belongs to which reader.
I am Armen, an SEO consultant in Barcelona, and that problem is what hreflang is built to solve. This guide is the technical one: the actual code, the codes that are valid and the ones that silently fail, how hreflang interacts with canonical tags, and how to check it when Search Console will not help you.
What is hreflang?
Hreflang is an HTML attribute that tells search engines which language, and optionally which country, each version of a page is written for, and where its equivalents live. Google uses it to swap in the right version for each searcher. It does not rank pages. It chooses between pages you already have.
A useful way to think about it: hreflang is a seating plan. The guests (your pages) are already in the room. Hreflang only decides who sits at which table.
Two things it is not. It is not how Google detects the language of a page, because Google’s own documentation says its algorithms work that out from the content. And it is not a command. Google treats it as a strong hint, and it ignores hints that contradict each other.
What does an hreflang tag look like?
A basic tag sits in the <head> of the page and names one alternate version:
<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/rooms/" />On a real site you never have one tag. Every page lists every version of itself, including its own URL, plus a fallback. For our hotel, the English rooms page would carry this block, and so would the Spanish and Catalan rooms pages, identically:
<link rel="alternate" hreflang="en" href="https://example.com/en/rooms/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/habitaciones/" />
<link rel="alternate" hreflang="ca" href="https://example.com/ca/habitacions/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/rooms/" />Notice the URLs are absolute, with the protocol included. Google requires fully qualified URLs, so /es/habitaciones/ on its own will not do.
The x-default line is the fallback for anyone whose language matches none of your versions. A searcher in Amsterdam with a Dutch browser gets the English page here. Often x-default points at a language picker page, which is also fine.
Which hreflang codes are valid?
The language comes first, in ISO 639 1 format (two letters, such as en, es, ca). The region is optional and comes second, in ISO 3166 1 Alpha 2 format (two letters, such as GB, ES, MX). That is the whole grammar, and most invalid codes break one of those two rules.
en English, any countryen-GB English, United Kingdomes-MX Spanish, Mexicoca Catalan, any countryzh-Hant Chinese, Traditional scriptx-default the fallbacken-UK the country code is GBes-LA Latin America is not a countryen-EU the EU has no code hereen_GB underscore instead of hyphenGB a country with no languageca-CT Catalonia has no ISO country codeThe Catalan one catches Barcelona businesses more than anyone. There is no country code for Catalonia, so use ca on its own, or ca-ES if you genuinely only mean Catalan speakers in Spain. In practice ca alone is usually right, since Catalan is also read in Andorra and parts of France.
For Spanish, the same logic applies. If you have one Spanish version for everyone, tag it es and stop. Only add es-ES and es-MX when the pages actually differ in price or shipping. Splitting a language by country without changing the page just gives you two near copies to maintain.
How do you add hreflang: head tags, HTTP headers or the sitemap?
Google accepts three methods and treats them as equivalent. Pick one per site and use only that one. Mixing methods is legal, but when two methods disagree you have created exactly the contradiction Google discards.
1. HTML tags in the head. The examples above. Best for most small and medium sites, because you can see the tags by viewing the source, and most multilingual plugins write them for you.
2. HTTP headers. For files that have no HTML head, such as PDFs. A downloadable menu in two languages is a real case for a restaurant in Barcelona. The server sends a Link header with the response:
Link: <https://example.com/menu-en.pdf>; rel="alternate"; hreflang="en",
<https://example.com/menu-es.pdf>; rel="alternate"; hreflang="es"3. The XML sitemap. Best for large sites. Each <url> entry lists every alternate, including itself, and you declare the xhtml namespace at the top:
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://example.com/en/rooms/</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/rooms/"/>
<xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/habitaciones/"/>
<xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/rooms/"/>
</url>
<!-- then one <url> block for the Spanish page, with the same links -->
</urlset>The sitemap route keeps the pages light, and it moves the logic into one file your developer can generate. The catch is that nobody sees it. A sitemap that stopped updating after a migration can sit wrong for months.
My opinion: under ten locales, use head tags. Above that, or on an ecommerce catalogue with thousands of products, use the sitemap.
How does hreflang work with canonical tags?
Each language version should carry a canonical tag pointing at itself, and every URL in your hreflang set should be that canonical URL. Get this wrong and the two signals cancel each other out.
The classic mistake: someone sets the canonical on the Spanish page to the English page, reasoning that the English one is the “original”. To Google that says the Spanish page is a duplicate that should not be indexed. The hreflang says the opposite. Google believes the canonical, drops the Spanish page, and your hreflang now points at a URL that is not in the index.
The subtler version is hreflang pointing at a URL with a tracking parameter, a missing trailing slash, or the http version. Each of those redirects or canonicalises somewhere else. Every URL in the set should return a 200 status and be the exact, indexable canonical form.
What are the most common hreflang mistakes?
The best known failures are missing return tags and missing self references, which we covered in detail on multilingual sites. These are the ones I see just as often that get far less attention:
- Tags that end up outside the head. Google stops reading the head when it meets an element that does not belong there, such as an
<img>or an<iframe>injected by a chat widget or a cookie banner. Any hreflang tags below that point are treated as body content and ignored. The page source looks fine to a human. The rendered version is not. - Every page pointing at the homepage. Some themes output the same hreflang block on every URL, linking each language to the other language’s homepage. It validates. It is also useless, because the rooms page needs to point at the other rooms page, not the front door.
- Tags added only by JavaScript. Google can render JavaScript, but hreflang that appears only after rendering depends on that render happening reliably. Server side output is the safer bet.
- Relative URLs. Covered above, and still one of the most common reasons a whole set is thrown out.
- Translated pages that are noindexed. Often a leftover from a staging environment. The hreflang set points at a page that asked not to be indexed, and the pairing collapses.
How do you test hreflang?
Crawl the site with a tool that reads the whole set, because Search Console no longer reports hreflang errors. Screaming Frog has a dedicated Hreflang tab once you enable hreflang crawling in the spider configuration, and its filters map neatly onto the mistakes above: missing return links, non canonical return links, noindex return links, incorrect language and region codes, and missing self reference. Sitebulb and Ahrefs Site Audit report similar issues.
Then check one page by hand in Search Console. Run the URL Inspection tool, open the tested page, and look at the rendered HTML. If your hreflang tags appear below a stray element, or do not appear at all, you have found a problem a desktop crawler that skips rendering can miss.
Finally, search like a customer. Change your Google interface language, or use a VPN set to another country, and search your brand name. It is crude, but it is the only test that shows you what the Manchester couple sees.
If this feels like more than you want to own, it is one of the first things our team checks in a technical SEO audit for any site with more than one language.
Does hreflang matter for Bing and AI answers?
Bing has said openly that hreflang is a weak signal for it, far weaker than the content language meta tag and the actual language of the page. If Bing matters to you, add <meta http-equiv="content-language" content="en-gb"> to each version too. It costs one line.
AI answers are less clear. Assistants such as ChatGPT and Copilot lean on Bing’s index for live search, and nobody outside those companies can tell you exactly how they choose between language versions. What helps everywhere is simple: each version fully written in its own language, with its own title and headings, not a translated shell around English content.
Where I would start
If you already run a site in two or more languages, do one thing this week: crawl it and open the hreflang report. Most of the sets I check have at least one silent break, and fixing it usually takes an afternoon, not a project.
If you are about to launch a second language, decide the codes before anyone writes a line of template code. Write the list down, with the exact canonical URL for each version. Hreflang goes wrong when it is improvised.
And if you want a second pair of eyes on it, that is exactly the kind of work we do as part of our international SEO service. Get in touch and tell me which markets you are trying to reach.
Frequently asked questions
Does hreflang improve rankings?
Not directly. Hreflang does not add authority or push a page higher. It tells Google which of your existing versions to show a particular searcher, so the Spanish page replaces the English one for someone searching in Spanish. The gain shows up as better click through and fewer bounces from people who landed on a language they cannot read.
Is hreflang case sensitive?
No. Google reads the codes without caring about capitals, so en gb in lower case works the same as the conventional form with the region in capitals. What does matter is the order (language first, then region) and the separator, which must be a hyphen character rather than an underscore.
Can I use hreflang across different domains?
Yes. Google explicitly allows the alternate URLs to sit on different domains, so a .es site and a .co.uk site can annotate each other. Both domains still have to carry the full set of return links, which usually means two teams or two CMS installs agreeing on the same list of URLs.
Does Bing use hreflang?
Only weakly. Bing has said publicly that hreflang is a far weaker signal for it than the content language meta tag and the language of the page itself. If Bing traffic matters to you, add a content language meta tag to each version as well as hreflang.
How many hreflang tags can one page have?
There is no published limit, but every tag adds weight to each page's head, and on large sites with many locales that gets heavy fast. Beyond roughly ten or fifteen versions, moving the annotations into the XML sitemap keeps pages light and gives you one file to maintain.
Armen Andonian
SEO Consultant in Barcelona
I'm an SEO consultant in Barcelona and founder of ACERO Digital. I help local businesses, ecommerce and international companies rank on Google and win customers from search.
LinkedIn →