Preventing Unknown Language Code Errors in HREFLang Elements

Some of the most common errors flagged in Google Search Console now days are for incorrect HREFLang deployments.   This week I was contacted by a site that had received a large number of errors appear in their Search Console.   They had recently updated their HREFLang Element tags for some critical pages of a new refresh and with XML site maps for the older pages.   From an article standpoint this was a perfect project as one site had nearly all of the most common mistakes that you can make implementing the HREFLang element on a site.

Below is a screen capture of one of the county specific sites from their Search Console.  Lets try to understand why they got the errors and how to fix them.


Incorrect Country or Language Code

The first error we see above is the "Unknown Language Code."   This is the most common error and as expected, they have the two most commonly used incorrect country and language codes.   In this case they have used the HREFLang tag embedded in the page.


In the image above, you see for Japan they have set the hreflang= element as jp-JP which is incorrect.  The correct ISO 639-1 Language Code is for Japanese is "ja" not "jp" which is actually the country code.  This is why Google listed it as an "Unknown Langauge" since there is not a language with the code "JP." If they update their code as shown below, it will fix the error.

<link rel="alternate" hreflang="ja-JP"href="" />

In addition to Japan, they made a mistake with the UK as well.  Note, Google listed the error not as an incorrect country code but the larger error, "no return codes" which means these en-uk pages have not been mapped for alternative pages. If they had, Google would have flagged the country error of using "en-uk" rather than "en-gb."  While 99.9999 percent of sites reference the United Kingdom with "uk" as their URL syntax, the correct ISO 3166 Country/Region Code is "GB" for "Great Britain."  Using "uk" and not GB you will get a unknown country error.  You can keep your URL syntax "uk" but you must update the "hreflang" element.

<link rel="alternate" hreflang="en-GB"href="" />

Using Country Code in place of Language Code

In the screen capture above, errors 4 - 8 the site owner incorrectly used the country code as the language code.  In the image below from their HREFLang XML site map.  This can happen when your URL syntax does not represent both country and language.  They apparently used a script that inserted their URL elements into the syntax but did not check for the missing language element.


The image above reflects multiple items which I have identified with different colored stars.

Blue Stars

The blue star next to hreflang-"cl" is one of the errors that is shown in Search Console.   The URL syntax shows this URL represents a page for Chile.  Since this Argentine page is also in Spanish, the correct site map syntax would be as shown below - identifying the page as being in Spanish for Chile.

<link rel="alternate" hreflang="ja-JP"href=""/>

Red Stars

Interesting that none of the listings with red stars were flagged by Google as being incorrect even though they are incorrectly assigned the wrong language to these pages.  There are many countries that have a different language ISO code so it is important that they are set correctly.

The first red star for hreflang="ar" is incorrect because this page represents Argentina and is written in Spanish. However the hreflan="ar" element is telling search engines the page is in Arabic ("ar" is the two letter ISO code for Arabic language) and with no country assigned, search engines will use this page for all Arabic speaking countries.

To further complex things, the second red star for hreflang="be" is also incorrect because this page represents Belgium and is written in Dutch. However the hreflan="be" element is telling search engines the page is in Belarusian ("be" is the two letter ISO code for Belarusian language, the language of Belaruse).

Green Stars

The entries with the green stars are correct and seems only so since the country is the same as the language code which is why it is critical that you use the correct settings.

Switching Country and Language in HREFlang Syntax

Not as common a problem as the other two but one I was seeing occasionally is swapping the country and language codes in the syntax.  As we saw above, switching the country and language can have significant negative impact on your site.  was put together incorrectly.  I did not have access to their Webmaster Console to see what error Google shows, it is clearly incorrect.


The first red star shows the hreflang="ar-es" which tells is this page should be targeting Spain in Arabic.  The URL syntax is /ar so could be a global Arabic page but is actually a Spanish language page for Argentina.  Switching the country and language has a pretty dramatic impact on what the search engines read.

<xhtml:link rel="alternate" hreflang="es-ar" href="" />

The second red star show hreflang="be-nl" which says this is a Belarusian language page targeting the Netherlands.  This should be switched to so this is a Dutch language page representing Belgium.

<xhtml:link rel="alternate" hreflang="n-bel" href="" />

Similar problem for the two obvious Canadian pages.  Using "ca" in the language position tells the search engines this page is written in Catalan which is spoken primarily in northern Spain.

Attention to Detail Required

It is critical when developing your HREFLang elements either in the page or in XML site maps that the country and language elements be correct.   This is one of the reasons we have spent a significant amount of time ensuring all of the mappings in our HREFLang XML site map builder are correct.




Speak Your Mind