Skip Navigation
September 6, 2017

The hreflang attributes tell Google about available translations for content. When used correctly, they can dramatically improve search engine positioning, because Google will understand what version of your content to display for people in different places. These tags help your site’s SEO in different languages.

hreflang attributes help Google display the right content in search results

When you search for something in Google, Google knows where you are located and what language you speak. Your location is obvious. Google gets it from your IP address. The browser tells Google what language you prefer (information that Google combines with your geographical location).

So, Google knows where you are and what language you prefer.

The hreflang attributes allow websites to tell Google which translations (or country-specific content versions) you offer for people in different places, speaking different languages.

You can probably already see the potential that hreflang hold. Using hreflang, you can push up language-specific and country-specific content to people speaking these languages and in these countries.

Of course, for this “magic” to happen, some conditions have to exist.

Required conditions for hreflang to work correctly

Before we go into the technical requirements, remember the most important requirement of all (and the an obvious one too). The hreflang attributes tell Google about content that is essentially the same, just in different languages or localized to different languages. If you use hreflang tags to tie together content that’s significantly different, you will only confuse Google. As a result, don’t expect any good results. So, rule #1 is to use hreflang tags to connect between the same content in different languages (a.k.a translations) or between content that’s just localized to different countries.

Now we start with the technicalities of implementing hreflang for your content.

HTML documents include a header and a body. The hreflang tags must appear inside the header. They need to look like:

hreflang links in

Include complete sets of documents with hreflang

We understand that hreflang attributes indicate to Google about available translated or localized content. So it follows that if item-B is equivalent to item-A, then also item-A is equivalent to item-B. That’s pretty obvious.

This means that items connected using hreflang need to form complete sets. All items in the set have to link to all other items. Google also requires that items link to themselves.

For example, a piece of content is available in English, French and Spanish, the English version has to link to the French and Spanish versions, as translations and also to itself.

hreflang links between languages

How WPML creates hreflang tags?

The value of the hreflang attribute identifies the language (list of language codes) and optionally the region (list of region codes) of an alternate URL.

That means that if you have geographically unspecified users, the hreflang follows a single two-letter format according to standard codes.

You could have fr, for French content, independent of region. Or you may have specific URLs for French speakers in Canada (fr-CA) or France (fr-FR), where the second term corresponds to the region and should be set according to the international rules.

For example:

  • fr: French content, independent of region
  • fr-CA: French content, for users from Canada
  • fr-FR: French content, for users from France

WPML retrieves this value using the Language Tag setting found on the WPML -> Languages page, at the Edit Languages link of the Site Languages section. WPML uses the Default Locale value as a fallback but it will never use the language Code, and if it can’t find one, it won’t render a hreflang for that language.

New installations of WPML already have the language tag properly filled. However, WPML always tries to adjust these codes when rendering the hreflang elements and find the best and more complete value. To do this, it will sometimes replace the underscores with a dash and make the string lowercase.

For example, let’s say that you have the following values – regardless in which field they are stored:


esp_es  (that’s possible!)

WPML takes esp_es and transforms it into esp-ES.

However, even though WPML does its best to render the right hreflang, it is not able to check if it has valid format or not. For example, an es-ES hreflang should match the language-country structure as we mentioned before. WPML is not able to warn you if you are using an invalid country-language format instead.

How to add hreflang with WPML

When you use WPML to build multilingual WordPress sites, you get the hreflang attributes automatically. By default, WPML will add hreflang as close as possible to the beginning of the <head> section. You can control it from WPML -> Languages -> SEO Options.

The SEO Options sections in WPML -> Languages
The SEO Options sections in WPML -> Languages

WPML will include the correct hreflang links in the site’s header. These tags will link to all available translations and to the same language. If an item is translated to only part of the site’s languages, WPML will include hreflang links only to these languages.

The option to display the hreflang link attributes at lower priority is a fallback, which is useful if some themes trigger WPML initialization too early. In addition to the position of these tags in the header, you can control the language/locale codes that WPML will output in the tags.

How to optimize hreflang to serve the content for the right audience

Remember that the hreflang links help you indicate to Google for which audience different versions of the content are intended. You can tell Google that the content is intended for an entire language or for a combination of language/country (which we call the “locale”).

Which option should you choose? This depends on how your site’s content is organized. Some sites have different content, in the same language, for people in different countries. That content can be very similar with only minor differences (like different currencies, contact details or purchase instructions). When you use hreflang, you tell Google that the content is not duplicate, but intended for different countries.

Multilingual sites that have content in several languages, but not specialized for different countries, should use hreflang attributes with just language information.

Check your hreflang settings and make sure they are as you intend them to be

Now that you understand the purpose and usage of hreflang, it’s time to make sure that you are using them correctly.

Go to WPML->Languages and click on the Edit Languages link. Check the Language tag column. If you want to tell Google that content is intended for countries, the values in this column should contain pairs of language and county (like en-US and fr-FR). If content is designed for languages, without distinction per country, these values should include only the languages (like en, fr).

Editing the language code (click image to zoom)
Editing the language code (click image to zoom)

Google lets you see issues related to the hreflang tags in your site. Log in to your Google Webmasters account, select the site to review and go to Search Traffic->International Targetting.

There are Language and Country tags. Depending on your targeting, check the tag that’s relevant for your site.

If all is well, you should see a count of items that have hreflang link attributes an none with errors.

Debugging problems with hreflang

You may get a warning from Google Webmaster that there are problems with hreflang in your site.

To check what’s happening, go to Google Webmasters and navigate to Search Traffic->International Targetting.

You will see a graph with the problems that Google detected:

Problems report for hreflang
Problems report for hreflang

What you’re seeing is the mismatch between hreflang links, captured by Google, at the time of indexing the site. This can mean that your site actually has a problem, or it means that content changed while Google was indexing your site. Since it takes Google weeks to re-index a site, this is a very possible option (happened on our site).

Click on any of the languages to get a list of URLs that Google sees as problematic.

URLs with hreflang problems for a selected language
URLs with hreflang problems for a selected language

Now, click on any of the links to go to these pages and look into the page source (CTRL-U in most browsers).

Page source with hreflang links
Page source with hreflang links

Follow these links in ALL languages and see that they all link to each other and to themselves. Also, check that the language codes are valid. Valid language codes contain either only the language or a combination of language-country.

If it’s all good, your site should be OK.

When you see that the translation sets are OK but you are still getting the error in Google Webmasters, give Google a few days to update its index. Normally, the reports should go down, as Google sees the translations as a consistent set. For example, the errors reported for our site as a result of us switching language codes. Google’s index had some pages with the old codes and some with the new codes. Naturally, this means that the translation set was broken. It gets fixed as Google’s index is refreshed.

If you continue getting the error in Google Webmasters, you need to be aware that Google’s detection and processing of hreflang tags is not very fault-tolerant and you need to get it precisely correct. As we previously mentioned, hreflang tags are only valid in the header of the HTML document.

During the parsing of an HTML document, the body begins when body tag is detected or when an element that belongs inside the body is detected – whichever comes first. So, when Google is looking for a hreflang annotation, it stops looking as soon as it detects the de facto beginning of the body.

That being said, run a HTML validation tool, and verify that there is not any HTML code in your header that is pushing your hreflang elements to the body.

If you are seeing some links missing, going to invalid URLs or with invalid language codes, it’s something that you need to handle. Let us know, in WPML support forum, which URLs are causing a problem and WPML support team will assist.

Got feedback, questions or ideas?

We want to get your feedback. This page is closed for comments, but the announcement blog post is open. To ask questions, make suggestions or leave any feedback, go there and leave your comments.