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.




HREFLang Builder Benefits

Multinational companies have struggled for years to get the local versions of their site ranking in their respective countries.  Most rank reports have simply recorded any page ranking as a win without consideration to it being the correct page.  Not having the local version of the page ranking creates problems with language, currency

Benefits of HREFLang XML SIte Maps Builder

There are a number of key benefits to using our HREFLang Builder:

Time and Cost Savings: 

Without HREFLang Builder, a global company typically spends 20 to 50 hours to manually develop and implement HREFLang XML Site Maps.   Due the size of the files and number of URL’s it cannot be managed in Excel.  The alternative is to embed HREFLang elements in the pages which adds 3kb to 80kb of text depending on the number of entries slowing down pages.  Additionally, estimated development costs between $15k to $60k and 3 to 6 months to add into the CMS. 

For an organized site, using HREFLang Builder takes less than 1 hour to implement.   

Importing & Mapping Alternative Pages to Each Other

HREFLang Builder imports URL’s from existing XML maps, Excel, CSV, Deep Crawl and Screaming Frog segmenting them into countries and language.  The HREFLang element works by telling the search engine that pages B and C are alternative language versions of page A.  You then have to state that they are also alternates to each other.

We built a Regular Expression Engine that would detect the one of 127 different URL structure formats used to designate country and/or language.   By using regex rules, we can accommodate for the use of multiple variations and even parameters in the URL’s which makes this scalable for even the most dysfunctional web operations team.  

Error Detection and Management

Submitting hundreds of error laden XML site maps can be devastating to a site’s crawl budget.  Search engines will reduce their crawl rate significantly if even 1% of the submitted pages in a site map have errors resulting in significant missing pages.  URL’s are checked for robots, canonical, and header rules. By excluding pages with errors from the final XML exports we ensure that 100% of submitted URL’s can be indexed quickly maximizing crawl allocation.  These error reports can be exported and shared.

Dynamic Updates

Manual updates would labor intensive so once a job is created it can be refreshed automatically at a desired interval then export or upload new XML files.   

Missing Language Pages Monitoring

Our Missing Pages mapping function was originally developed to find gaps in country URL lists.   It has become a popular tool to monitor missing, non-localized and in some cases, rogue market pages.  As many CMS systems do not create a page if it has not been localized many pages may be missing from dynamic XML site maps. 

The implmentation of HREFLang XML site maps has lead to significant opportunity recovery for clients, which is the reason this product should be used by every multinational to quickly and easily manage the inclusion and of their gloal XML site maps.   


Manage HREFLang Files

The HREF Builder allows you to manage and quickly update HREF XML files as your content changes.   We have multiple methods to keep yoir files updated from, new Excel or CSV uploads, fetching XML index and individual XML files and dynamically updated your HREF files.


Why Use the HREFLang Element?

While there are many applications of the  HREFLang Element, it was designed to do one thing, tell the search engine YOUR preference for the desired content to be shown to a language-specific audience.

Even the mighty Google makes mistakes when matching users to content in their own search engine.  While you cannot guarantee this is the page that will actually be shone, it is the strongest signal you can possible give the search engine to help them determine which is correct.

Key Applications of the HREFLang Element

  1.  Ensure Local Market Content is correctly Represented - This is the main benefit of using the HREFLang Element.  It allows you to tell Google that that page is specific to India or Australia.   This helps ensure your product page with local pricing, offers and contact information is correct for that market.
  2. Identify Global and Regional Language Content - To help the search engine understand what is global English or Spanish content from what is local market specific content. This is helpful to a English or Spanish searcher traveling in another country that is looking for support information.  For example, I was Paris France and wanted to find the what time the Hertz car rental office closed.  I did my search in English and was able to get a global English page that had the closing times and phone numbers along with the French page.
  3. Ensure Local Market Home Pages are Represented Correctly - To ensure when a brand name search is done the local market home page is represented in the search engine vs. a global or more dominate market language page.
  4. Enable the Global use of Dot-com domains - For many companies managing local market ccTLD domains for all of their markets is cost prohibitive.  By using a .com domain with country/language directories and the HREFLang Element you can reduce your costs and have proper representation in the local markets.
  5. Help Support Legal Case on Local Licenses - companies have been sued by partners for not adequately representing their relationships in specific markets.  In addition, you can potentially limit your exposure in markets where you should not be seen due to sales rights and other legal issues.   The use of the HREFLang is strong support of your case that you made an effort to segment and isolate content for specific markets.

There are my more applications of the HREFLang Element that we will cover on the blog and on this page over time but for now, using the tool to help the search engines match the correct content to your target market is the best application of all.


HREFLang Tag Overview

The HREFLang Tag is a meta tag that helps search engines understand the relationships of local country and language versions of similar pages.  By implementing it you acknowledge potential duplication of content and signal your specific request to have them associated with their representative countries or languages.

Sample Code Snippet

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

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

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

rel="alternate" href="" hreflang="en-au" />

In this example above from a Global Home page that also acts as the US home page, we are are telling the search engine the following: We have 4 versions of the same page but they are unique to their respective counties.  In this case the home page for the US, UK, Spain and Australia are country alternatives of each other.

When to Use HREFLang Tags?

If you have multiple country or language versions of your website you are a prime candidate for this functionality.  Especially if you have multiple English and/or Spanish language versions of the site this can be helpful in distinguishing them apart.  It is very common for Google especially to show a global or US page in a local search engines.   If you review some of the case studies such as the Absolut Vodka HREFLang Case Study you will see that when they added the HREFLang XML site map it almost immediately corrected their listings in the search engines increasing local traffic exponentially.

Required Elements:

You MUST include a reference to the page you are placing the code as well as all alternative pages.  In the example above we have 4 alterniave pages and all 4 pages have this same block of code.

Pros of HREFLang Tags

The biggest pro to using HREFLang Tags in your pages is they ensure a 1 to 1 match to each of the alternative pages.  This of course is If you are currently using a localized folder structure for your site this is often the ONLY method available as it requires your CMS logic to match the different language versions.

Cons of HREFLang Tags

Note:  Hreflang is only a signal to the search engines and not a specific directive and other factors such as links from a specific market can cause a different country or language version to rank higher in the local market.  However, in our experience of doing hundreds of HREFLang implementations they have worked in nearly 100% of the time.


HREFLang for Regional Sites

Many sites try to cover a large area of the world with a regional site like LATM for Latin America or APAC for all of Asia.  The problem is there is no country setting nor is there any provision with the HREF Language settings.  What has worked for a number of my clients is to set that regional site to represent the various countries in the region. For example, HP has a single home page to represent Spanish speaking countries in the Central/Latin America region   Which has resulted in a less than optimal search result for these markets. Using Costa Rica as an example – where the global page is the page that is ranking and the site links are for Latin America, Spain, Central America and even UK for flavor. regional Sort of creating a site specifically for Costa Rica HP only has two ways to try to improve this result:

Option 1 – Set the regional Site to Global Spanish

This option is not perfect but should at least tell Google this is our Global Spanish language version and this should replace the global home page. <xhtml:link rel="alternate" hreflang="es" href=""/> and that would make all of the non-included Spanish countries use the Latin American version. Since the major countries are covered this might be a better solution that using the x-default and setting English.

Option 2 – Make the Regional Site the Alternate for Each Country

As the bulk of Spanish speaking countries are in this region, it can be safe to set it as the global Spanish version as in Option 1.   However, to maximize the alignment to the specific countries we suggest mapping the regional page to the various markets using HREFLang XML site maps.   Note, I have vetted this with Google and they have confirmed there are no issues with implementing this approach.

Costa Rica <xhtml:link rel="alternate" hreflang="es-CR" href=""/>

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

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

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

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

El Salvador <xhtml:link rel="alternate" hreflang="es-SV" href=""/>

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

This is easy to do in our HREF Builder to map these to the various countries and build out the HREF XML.  


What's Indexed Tool

This is a tool that I developed a number of years ago and I have added it into the HREF Builder suite.  This tool used the Info: command in Google to see which of the URL's are indexed. It started to solve the problem of submitting a number of pages  to Google on a site map and only a small set are indexed.  I had no way of knowing which pages were not indexed.   In the example below, the site map for Argentina has 524 pages but only 5 are indexed. submitted-vs-indexed This tool can import your XML site map or CSV file and using the info: command will tell you what pages are an are not indexed and for those that are the cache date to monitor how recent the page was added.

Business Applications:

  1.  XML SIte Map Diagnostics - the original purpose to identify those pages submitted to Google but not yet indexing.
  2. Post Launch Reindexing - you can monitor how long it takes for Google to index the new pages on the site.
  3. Post Launch Deindexing - you can monitor how long it takes for Google to drop your pages from their index


Reducing Language Errors in Google Webmaster Tools

If you received a notification from Google that you have language errors on your site you can correct them by creating and mapping a complete set of HREF XML Site Maps. href_errors


HREF Language XML Builder

Back Azimuth Consulting's HREF Builder is a cloud-based application that quickly builds HREF XML files to helps the engines understand the county, language and regional nuances of your content.  With HREF builder you can quickly load, map and export a complete HREF XML for each country version.  We have also integrated a number of filters to account for the multitude of different URL structures.


HREF Builder Launches

While this tool actually was publicly announced at PubCon Vegas in 2013 it is just now becoming tool available to the public.   This is one of the most robust tools to develop HREF XML sitemaps on the market.   There are a few free web and Excel tools that can get you started but they all have significant limitations.

This tool came from the specific needs or medium and larger sites that have large numbers of URL's that cannot be presorted and aligned prior to the tool being used.