hreflang for English and Spanish versions of a site

What hreflang does

Lighthouse's documentation explains it. Many sites provide different versions of a page based on language or region. hreflang links tell search engines the addresses of all the versions of a page, so they can show the right version for each language or region.

For an English and Spanish site, the English page says "this is the English version, and the Spanish one is over there", and the Spanish page says the same in return. Without it, search engines have to guess which pages belong together and which to show to whom.

hreflang is a signal for search engines, not for the browser. It does not translate anything or redirect anyone.

The three ways to declare it

Lighthouse lists three, and says to choose the easiest for your situation.

1. Links in the head of each page:

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

2. A `Link` header in the HTTP response, useful for files that have no HTML head, such as PDFs.

3. Language information in your sitemap, with an xhtml:link entry for each version.

The 2025 Web Almanac found hreflang on about 20% of pages, roughly double the 9 to 10% of the year before. Almost all of it is in the page, not in a header: the header form was on 0.1 to 0.2% of pages. Raw and rendered numbers differed by less than 1%, which suggests that most sites that use it do so in a way that survives rendering.

The rule that matters most: every version points to every version

Lighthouse says each version of a page must link to all the other versions, including itself. Otherwise search engines may ignore the links or interpret them incorrectly.

So the English page carries three links: to the English page, to the Spanish page, and x-default. The Spanish page carries the same three. If the English page lists the Spanish one but the Spanish one does not list the English one, the pair is incomplete.

The examples in the documentation use full addresses, with https and the host, and so should you.

x-default

For a page where users select their language, Lighthouse says to use the x-default keyword:

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

It names the version to show when no language matches. The Almanac found x-default on about 7% of home pages, nearly as often as en.

Codes: language and, optionally, country

Lighthouse's guidelines:

• The hreflang value must always specify a language code.
• The language code must follow the ISO 639-1 format, for example en and es.
• It can also include a region code, for example es-mx for Spanish speakers in Mexico or es-cl for those in Chile.
• The region code must be an ISO 3166-1 alpha-2 country code, which is two letters.

Two consequences for a Spanish version:

• Latin America is not a country. A code such as es-419 is a valid way to name Latin American Spanish in the lang attribute, where MDN notes that :lang(es) matches both es-ES and es-419, but the guideline for hreflang says the region must be a two-letter country code. For a Spanish page meant for many countries, use plain es. If you serve a specific country differently, add an entry for it, such as es-mx.
• Language first. Do not use a country alone. If your Spanish page is for everyone who speaks Spanish, es is the right value.

Lighthouse checks the language codes in your hreflang links and reports invalid ones. It does not check region codes, and it does not check your sitemap.

Also set the page's own language

The lang attribute on the html element names the language the page is written in. MDN says to always specify it, and notes that WCAG success criterion 3.1.1 requires a page's language to be programmatically determined, and 3.1.2 requires parts in a different language to be marked. The purpose, MDN says, is mainly to let assistive tools such as screen readers use the right pronunciation.

<html lang="es">

A Spanish page with lang="en" is read aloud with the wrong voice, and sends mixed signals to anything that reads the attribute. A short passage in another language gets its own lang, for example <span lang="en">checkout</span>.

Canonical links and language

Each language version should have a canonical link that points to itself. Lighthouse's canonical audit fails a page whose canonical points to a page for a different region or language. If your Spanish page's canonical points to the English page, you are telling search engines that the Spanish page is a duplicate of the English one, which contradicts your hreflang links. See canonical tags.

Keep the pair consistent

• Every address in a hreflang link should return a 200. Do not point to a page that redirects, is missing, or has a noindex. See redirects and status codes and robots.txt and noindex.
• Use one method for the same pair, or make sure the methods agree.
• When you add, rename or remove a page in one language, update its partner and the links.

A language switch for visitors

hreflang is for search engines. Visitors need a visible switch between languages, on every page, that takes them to the same page in the other language. Remember their choice. Avoid sending people to a language from their browser's setting with no way back, because the guess is sometimes wrong. Mark the switch link itself with hreflang and lang attributes for the language it leads to.

Speed and language versions

A second language doubles the number of pages. A few things matter for speed:

• Fonts. Check that your web font includes the accented letters and the inverted question and exclamation marks that Spanish needs. If a character is missing from the font, the browser draws it in a fallback font, which can cause a flash or a shift. See web fonts.
• Caching. Each language is a separate address, so a page cache keeps them apart. Check that a language switch does not depend on a cookie that bypasses the cache.
• Images. Reuse the same files for both languages, rather than duplicating them. Text inside an image needs a translated copy, which is one more reason to keep text as text.
• Redirects. A language redirect adds a round trip, so avoid sending every visitor through one.

How to check

1. View the source of an English page and look for the three links. Open the Spanish address and check that it carries the same three.
2. Check the `lang` attribute on each page.
3. Check each canonical points to its own page.
4. Run Lighthouse and read the hreflang finding.
5. Test the switch from several pages, to be sure it lands on the matching page and not the home page.

Mistakes to avoid

• Links that do not point back.
• No self-reference.
• Wrong or made-up codes, or a country in place of a language.
• A canonical that points to the other language.
• hreflang to redirected, missing or `noindex` pages.
• A Spanish page labeled `lang="en"`.
• Machine-translated pages that no one has read, left live. A visitor who lands on one decides quickly whether to trust you.

Check your own page

Run the free audit and read the hreflang finding. Then open one English page and its Spanish partner in the page source, and confirm that each has three matching links, its own lang and its own canonical.

Sources

• Document does not have a valid hreflang and Document does not have a valid rel=canonical in the Lighthouse documentation: the three ways, the self-reference rule, x-default, the code guidelines and the canonical failure conditions.
• SEO chapter, Web Almanac 2025: how common hreflang is, by method and by language.
• The lang attribute on MDN: language tags, inheritance and the accessibility requirements.