What is hreflang, and how do you set it up without errors?

Your website is in Spanish and English, or there is one version for the United Kingdom and another for the United States. To you it is obvious which one belongs to each visitor. To Google it is not: without a hint, it may show the English version to someone searching in Spanish, or treat two near-identical pages for two countries as duplicate content and keep only one.

hreflang is that hint. A small tag, invisible to users and reputed to be tricky, mainly because its mistakes give no warning: if something is wrong, Google simply ignores it.

What hreflang is for

It tells the search engine: “this page has these equivalent versions in other languages or for other regions”. With that information, Google can show in its results the version that matches the searcher’s language and country.

It is worth being clear about what it does not do. It translates nothing, redirects nobody and does not improve rankings in itself. Nor is it a command: it is a signal Google weighs alongside others. Its effect is that the right person reaches the right version.

The most common form is a list of links in the <head> of each version:

<link rel="alternate" hreflang="en" href="https://example.com/en/services/" />
<link rel="alternate" hreflang="es" href="https://example.com/servicios/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/servicios/" />

It can also be declared in the HTTP header (useful for files without a <head>, such as a PDF) or in the XML sitemap, which is convenient when there are many languages. The sensible approach is to pick one method and stick with it: two sources for the same thing end up contradicting each other.

The three rules: reciprocity, self-reference and x-default

Reciprocity. If the Spanish page declares that its English version is a given URL, that English URL must in turn declare the Spanish one. A one-way link is discarded. It is a safeguard against abuse: it stops anyone from declaring your page to be “their English version”.

Self-reference. Each page includes itself in its own list, with its own language. It looks redundant, but it means the set is identical across every version and there is no doubt about which page belongs where.

x-default. This is the version for anyone who matches none of the declared languages. If your site is in Spanish and English and someone searches in German, x-default tells Google what to offer them. It usually points to the main version or a language selection page. It is not mandatory, but without it that decision is left to the search engine.

How language and region codes are written

The hreflang value has two parts:

• The language, required, using the two-letter code from ISO 639-1: en, es, pt, fr.
• The region, optional, using the two-letter country code from ISO 3166-1: GB, US, IE, CO, MX.

They are written in that order and joined by a hyphen: en-GB, es-CO. A region on its own, without a language, is not valid.

The region is only needed when there genuinely is a different version per country: another currency, other prices, other delivery terms or other legislation. If your English works equally well everywhere, plain en is correct. With en-GB you would be telling Google that page is for the United Kingdom, and someone searching from Australia might be offered something else.

The most common code mistakes:

Written	Problem	Correct
en-UK	the ISO code for the United Kingdom is GB	en-GB
en_GB	underscore instead of a hyphen	en-GB
es-LA	LA is Laos, not Latin America	es
GB	region without a language	en-GB

The underscore has an explanation: it is the format og:locale uses in Open Graph tags, and it sometimes gets copied from one to the other.

hreflang and canonical, together

The two tags must tell the same story. Each version must be canonical to itself. If the English page declares the Spanish one as canonical, it is telling Google the English version is a duplicate, and the search engine will follow the canonical and discard the hreflang.

By the same logic, the URLs listed in hreflang must be the final ones: they should respond directly with the page, with no redirect, no error and no noindex. An hreflang pointing at an address that redirects forces Google to guess; why that matters is covered in 301 vs 302 redirects.

Typical mistakes

• Adding a language without updating the existing ones. The new page declares every version, but the existing pages do not declare it. This is the error Search Console calls “no return tags”.
• Pointing to the other language’s home page instead of the equivalent page. Each page should link to its twin, not to the home page.
• Mixing variants of the same URL: with and without a trailing slash, with and without www, http and https. To Google they are different addresses, and reciprocity breaks.
• Declaring translations that do not exist, or pages that in the other language are only a summary. If there is no equivalent version, it is better to declare none for that page.
• Automatically redirecting by location or browser language. Googlebot crawls mostly from the United States and might never see the other versions. It is better to suggest switching language with a notice or a selector, without forcing it.
• Copying the main language’s canonical to every version, the case described in the previous section.

If your site is moving from one platform to another, this is one of the pieces that most often breaks along the way, so it is worth checking before and after any migration.

What if my site has only one language?

Then you do not need hreflang. What is worth doing is declaring the language in the lang attribute of the <html> tag, which browsers use for automatic translation and screen readers for pronunciation. hreflang comes into play the day a second version exists.

Checking yours

The hreflang checker reads the tags on a URL, visits each alternate it declares (up to twenty), and for each one reviews its status, its canonical and its own alternates. From that it builds a matrix of who points to whom and flags what fails: alternates with no return tag, pages that do not include themselves, a missing x-default, badly written language or region codes, and canonicals that contradict the hreflang.

It is worth running it on one page per template (home, service, article) and repeating it whenever a language is added or the URL structure changes, which is exactly when broken return tags appear.

---

hreflang does not win you rankings, but it keeps you from losing them by showing the wrong version to the wrong person. Done well, nobody notices; done badly, nobody notices either, and that is precisely why it is worth checking.