Hreflang is one of the most poorly implemented elements of technical SEO. Google has confirmed that 75% of implementations contain errors that nullify their effect. The result: users landing on the wrong language version, duplicate content between language versions and loss of positions in international markets.
This guide covers correct technical implementation, the three available methods, the most common errors and how to validate everything works.
What hreflang is and what it does for international SEO
Hreflang is an attribute that tells search engines about the relationship between alternative versions of the same page in different languages or regions. When Google finds correctly implemented hreflang, it shows the most relevant version to each user based on their language and geographic location.
Hreflang solves two fundamental problems: the first is duplicate content between languages, where without hreflang Google may interpret your Spanish and English versions as competing duplicate content rather than alternative versions of the same page. The second is the wrong version appearing in search results, where a user in Barcelona searching in Spanish might see the English result if Google doesn’t know which version to serve.
It is important to understand what hreflang does NOT do:
- It does not redirect users automatically. It only influences which version appears in search results.
- It does not transfer PageRank between versions. Each version maintains its own authority.
- It does not replace canonical tags. Both are necessary and must be consistent.
Language and region codes
Hreflang uses ISO 639-1 codes for languages (es, en, ca, fr, de) and optionally ISO 3166-1 Alpha-2 for regions (es-ES, es-MX, en-US, en-GB). The language-region combination allows serving differentiated content not only by language but by geographic market.
Common errors with codes:
- Using “esp” instead of “es” (ISO 639-1 uses two letters).
- Using “uk” for British English instead of “en-GB”. In ISO 3166-1 alpha-2 the code for the United Kingdom is “GB”, not “UK”; “uk” as an ISO 639-1 language code corresponds to Ukrainian.
- Confusing “ca” (Catalan) with “ca-ES” (Catalan from Spain). Both are valid, but they mean different things: “ca” is generic, “ca-ES” is specific to Spain.
The 3 ways to implement hreflang: HTML, XML sitemap, HTTP headers
Google accepts three implementation methods. All three are equivalent in effect: you can choose whichever best suits your architecture. What you should not do is mix methods for the same page, as this can generate conflicting signals.
1. Link tags in the HTML head
The most direct option. You add a <link rel="alternate" hreflang="xx" href="URL"> tag for each alternative version, including the page itself (self-referencing).
2. XML sitemap
You declare the alternatives within the sitemap using the xhtml:link namespace. Each <url> entry includes an <xhtml:link> tag for each alternative version.
3. HTTP headers
You use the Link header in the HTTP response. This is the only option for non-HTML resources (PDFs, downloadable documents).
Which to choose
- HTML tags: ideal for sites with fewer than 10 language/region combinations. Easy to implement and debug.
- XML sitemap: preferable for sites with many languages (more than 10) because it does not add weight to the HTML. Also recommended when URLs follow predictable patterns.
- HTTP headers: only necessary for non-HTML content. Rarely the primary option.
HTML implementation: correct syntax and common errors
HTML implementation requires adding <link> tags inside the <head> of each page. There are three rules that must always be followed:
Rule 1: Self-referencing. Each page must include an hreflang pointing to itself. If the Spanish page has hreflang pointing to the English and Catalan versions, it must also have one pointing to its own Spanish URL.
Rule 2: Bidirectionality. If page A (Spanish) references page B (English), then page B must reference page A. If this reciprocity is missing, Google ignores the hreflang for that page pair.
Rule 3: Absolute URLs. All URLs in href attributes must be absolute (including protocol and domain), never relative.
A site with three languages (Spanish, English, Catalan) needs three hreflang tags on each page, plus an x-default tag if applicable.
The x-default attribute
x-default indicates which version to show when the user’s language does not match any of the available versions. If you have versions in Spanish, English and Catalan, a user searching in German will see the version marked as x-default.
Normally, x-default points to the main language version of the site or to a language selection page. It is not mandatory, but Google recommends it to improve the experience for users whose languages are not supported.
Hreflang in XML sitemap: when to choose this option
XML sitemap implementation is preferable when:
- Your site has more than 50 language/region combinations, which would add a lot of code to the HTML of each page.
- You generate the sitemap programmatically, facilitating consistency.
- You want to centralise hreflang management in a single file rather than distributing it across thousands of pages.
The sitemap structure with hreflang uses the namespace xmlns:xhtml="http://www.w3.org/1999/xhtml". Each <url> entry contains the main URL and all its alternatives as <xhtml:link> elements.
The main advantage is centralised management: if a URL changes, you only need to update it in the sitemap rather than across all pages that reference it. The downside is that any desynchronisation between the sitemap and the real pages creates silent errors.
Sitemap validation with hreflang
After implementing hreflang in the sitemap, verify that:
- All URLs in the sitemap return code 200 (not 301, 302 or 404).
- Each group of alternatives includes self-referencing.
- Language codes are valid according to ISO 639-1.
- There are no URLs with www and without www mixed together.
- The sitemap is accessible and referenced in robots.txt.
How to validate that your hreflang works correctly
Hreflang validation requires checking both the syntax and the logic of the relationships between pages.
Validation tools
Google Search Console — use the URL Inspection Tool to verify hreflang processing for individual pages, and review the Coverage and Indexing reports to detect international crawling issues. For bulk hreflang validation, external crawling tools like Screaming Frog or Sitebulb can audit alternate-link headers and language codes across the entire site.
Screaming Frog crawls all pages of the site and generates an hreflang report that identifies reciprocity problems, incorrect URLs and invalid language codes. It is the most comprehensive tool for hreflang audits at scale.
Ahrefs Site Audit detects hreflang errors as part of its general technical audit, including reciprocity issues and links to pages with redirects or 404s.
Manual validation checklist
For each page of the site, verify:
- All alternative hreflangs point to URLs that return code 200.
- Each referenced URL includes a reciprocal hreflang pointing back.
- Self-referencing is present.
- The canonical URL and the self-referencing hreflang URL match exactly.
- Language and region codes are correct.
- If x-default exists, it points to a valid and accessible URL.
The 7 most common hreflang errors and how to avoid them
1. Missing reciprocity
The most common error. The Spanish page links to the English version, but the English version does not link back to the Spanish one. Google ignores both signals when reciprocity is missing.
Generate hreflangs programmatically from a centralised data source, ensuring that all versions reference each other.
2. URLs with 404 errors or redirects
An hreflang pointing to a URL that returns 404 or 301 is invalid. Google discards the signal and may treat the versions as duplicate content.
Regularly audit hreflangs with Screaming Frog to detect broken URLs. When you delete or move a page, update the hreflangs in all alternative versions.
3. Inconsistency with canonical
If page A has a canonical pointing to itself and hreflang pointing to B, but B has a canonical pointing to A (instead of to itself), the signals are contradictory. Google doesn’t know which is the preferred version.
Each page must have a canonical pointing to itself. The canonical and the self-referencing hreflang must match exactly in URL.
4. Incorrect language codes
Using “esp” instead of “es”, “eng” instead of “en” or “cat” instead of “ca”. Google exclusively accepts ISO 639-1 codes (two letters).
Consult the official ISO 639-1 code list and validate with automated tools.
5. Mixing www and non-www
If the canonical page uses https://www.example.com/ but the hreflang points to https://example.com/, Google treats them as different URLs.
Always use the same domain version (www or without www) in canonicals, hreflangs and internal URLs of the site.
6. Missing self-referencing
Each page must include an hreflang pointing to itself. Without self-referencing, Google cannot confirm that the page voluntarily participates in the group of alternatives.
Always include the page’s own URL in the list of hreflangs.
7. Hreflang on noindex pages
If a page has the noindex directive and an hreflang pointing to it, Google excludes it from the index but finds an hreflang signal pointing to a page that shouldn’t be in the results.
Do not include hreflang on pages with noindex. If a language version should not be indexed, remove it from the hreflang group of all versions.
Frequently asked questions about hreflang
Do I need hreflang if my website is only in Spanish?
No. If your site is in a single language and you don’t differentiate content by region (for example, es-ES vs es-MX), hreflang is not necessary. It only makes sense when alternative versions of the same page exist in different languages or for different countries.
Does hreflang distinguish between es-ES and es-MX?
Yes. You can use language-region codes like es-ES (Spanish from Spain) and es-MX (Spanish from Mexico) to serve differentiated content to users in each country. Google respects this distinction and shows the most appropriate regional version in search results.
What happens if hreflang has errors? Does Google ignore it?
When Google detects errors such as missing reciprocity or incorrect URLs, it ignores the hreflang signals for those specific pages and falls back to its own algorithms to determine which version to show. The result may be that users see the wrong version of your page in search results.
A correct hreflang implementation is essential for any multilingual site that wants to rank in different markets. If a crawl of your site has surfaced any of these issues, the next step is gauging their real scope. Contact our team for a no-obligation technical assessment.
Share this article
If you found this content useful, share it with your colleagues.
Frequently Asked Questions
¿Con qué frecuencia publican contenido nuevo?
Publicamos artículos nuevos semanalmente, enfocados en las últimas tendencias de SEO técnico, casos de estudio reales y mejores prácticas. Suscríbete a nuestro newsletter para no perderte ninguna actualización.
¿Los consejos son aplicables a cualquier tipo de sitio web?
Nuestros consejos se adaptan a diferentes tipos de sitios: ecommerce, blogs, sitios corporativos y aplicaciones web. Siempre indicamos cuándo una técnica es específica para cierto tipo de sitio o requerimientos técnicos.
¿Puedo implementar estas técnicas yo mismo?
Muchas técnicas básicas puedes implementarlas tú mismo siguiendo nuestras guías paso a paso. Para optimizaciones avanzadas o auditorías completas, recomendamos consultar con especialistas en SEO técnico como nuestro equipo.
¿Ofrecen servicios de consultoría personalizada?
Sí, ofrecemos servicios de consultoría SEO técnica personalizada, auditorías completas y optimización integral. Contáctanos para discutir las necesidades específicas de tu proyecto y cómo podemos ayudarte.
