Warningindexing.hreflang-codes

Language codes search engines don't recognise

Why it matters

hreflang tells search engines which language, and optionally which country, each version of a page is for, so a visitor in Germany is shown the German page. Google reads only real codes: "Only language codes listed in ISO 639-1 and region codes listed in ISO 3166-1 Alpha 2 are supported; other codes that aren't listed in those standards, such as es-419, aren't supported." A code it can't read is a version it doesn't know about, and the wrong one turns up in that country's results.

The usual mistakes are a country where the language goes (jp for Japanese, which is ja), en-UK (the United Kingdom's code is GB: "using EU, UN, or UK in hreflang annotations doesn't have an effect on Google Search"), and an underscore (en_GB). Google also warns: "You can't specify the country code by itself." Some country codes are real languages too (uk is Ukrainian, se Northern Sami), and those are taken at their word. A language with no two-letter code at all (Cebuano, Filipino, Cantonese) can't be named to Google, which is nobody's mistake, so that is only a notice.

Whether each version links back to the others is a question about the whole site, which indexing.hreflang-pairs answers for monitored sites. This rule reads the codes in the page's HTML, not in a Link header or the sitemap.

Sources: Google's supported language and region codes and common hreflang mistakes.

How to fix it

A language from ISO 639-1, then optionally a region from ISO 3166-1, joined by a hyphen:

<link rel="alternate" hreflang="en-GB" href="https://www.example.com/cakes" />
<link rel="alternate" hreflang="ja" href="https://www.example.com/ja/cakes" />
<link rel="alternate" hreflang="zh-Hant" href="https://www.example.com/zh-hant/cakes" />
<link rel="alternate" hreflang="x-default" href="https://www.example.com/cakes" />

Translation plugins (WPML, Polylang, Weglot) take the codes from each language's settings, so a wrong code is usually fixed in one place there.

A language with no two-letter code can't be given one. Its version can stay for the people who pick it, and an x-default version (a language chooser, say) is where Google sends readers whose language isn't listed.

Examples

These are the rule's own test pages, and what it says about each. They are run on every change to the rule book.

<html lang="en">
<link rel="alternate" hreflang="en" href="https://www.example.com/cakes">
<link rel="alternate" hreflang="jp" href="https://www.example.com/jp/cakes">
<link rel="alternate" hreflang="en_US" href="https://www.example.com/us/cakes">

Warning2 hreflang codes on the page aren't ones Google reads, so it ignores those versions: "jp" (a country, not a language: Japanese is ja), "en_US" (an underscore, where Google reads en-US).

fail-country-codes
<html lang="en-GB">
<link rel="alternate" hreflang="en-UK" href="https://www.example.com/cakes">
<link rel="alternate" hreflang="de" href="https://www.example.com/de/kuchen">

WarningAn hreflang code on the page isn't one Google reads, so it ignores that version: "en-UK" (UK isn't a region code, so Google ignores it: the United Kingdom is GB).

fail-en-uk
<html lang="en-GB">
<link rel="alternate" hreflang="en-GB" href="https://www.example.com/cakes">
<link rel="alternate" hreflang="ja" href="https://www.example.com/ja/cakes">
<link rel="alternate" hreflang="zh-Hant" href="https://www.example.com/zh-hant/cakes">
<link rel="alternate" hreflang="x-default" href="https://www.example.com/cakes">

PassedEvery hreflang code on the page is one Google reads (4 language versions).

pass-language-versions