Document doesn't have a valid hreflang

— Updated
Appears in: SEO audits
On this page

Many sites provide different versions of a page based on a user's language or region. hreflang links tell search engines the URLs for all the versions of a page so that they can display the correct version for each language or region.

How the Lighthouse hreflang audit fails #

Lighthouse flags incorrect hreflang links:

Lighthouse audit showing incorrect hreflang links

Lighthouse checks for hreflang links in the page's head and in its response headers.

Lighthouse then checks for valid language codes within the hreflanglinks. Lighthouse reports any hreflang links with invalid language codes.

Lighthouse does not check region codes or your sitemap.

How to define an hreflang link for each version of a page #

Suppose that you have three versions of a page:

  • An English version at https://example.com
  • A Spanish version at https://es.example.com
  • A German version at https://de.example.com

There are three ways to tell search engines that these pages are equivalent. Choose whichever method is easiest for your situation.

Option 1: Add hreflang links to the <head> of each page:

<link rel="alternate" hreflang="en" href="https://example.com" />
<link rel="alternate" hreflang="es" href="https://es.example.com" />
<link rel="alternate" hreflang="de" href="https://de.example.com" />

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

For pages that allow users to select their language, use the x-default keyword:

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

Option 2: Add Link headers to your HTTP response:

Link: <https://example.com>; rel="alternate"; hreflang="en", <https://es.example.com>;
rel="alternate"; hreflang="es", <https://de.example.com>; rel="alternate"; hreflang="de"

Option 3: Add language version information to your sitemap.

<url>
<loc>https://example.com</loc>

<xhtml:link rel="alternate" hreflang="es"
href="https://es.example.com"/>

<xhtml:link rel="alternate" hreflang="de"
href="https://es.example.com"/>

</url>

Guidelines for hreflang values #

  • The hreflang value must always specify a language code.
  • The language code must follow ISO 639-1 format.
  • The hreflang value can also include an optional regional code. For example, es-mx is for Spanish speakers in Mexico, while es-cl is for Spanish speakers in Chile.
  • The region code must follow the ISO 3166-1 alpha-2 format.

Resources #

Last updated: — Improve article
Return to all articles
Share