The ultimate guide

hreflang: the ultimate guide

April 05th, 2016 – 31 Comments

hreflang tags are a technical solution for sites that have similar content in multiple languages. A site owner wants search engines to point people to the most “fitting” language. Say a user is Dutch, the page that ranks is English, but there’s also a Dutch version. You would want Google to show the Dutch page in the search results for that user. This is the type of problem hreflang was designed to solve.

In this (very long) article we’ll discuss:

hreflang tags are among the hardest specs I’ve ever seen come out of a search engine. Doing it right is tough and takes time. This guide will try and prevent you from falling into common traps. Be sure to read it thoroughly if you’re embarking on an hreflang project.

Become a technical SEO expert with our Technical SEO 1 training! »

Technical SEO 1 training Info

What are hreflang tags meant for?

hreflang tags are a method to mark up pages that are similar in meaning but aimed at different languages and/or regions. You can use this for three types of variations:

  • Content with regional variations like en-us and en-gb.
  • Content in different languages like en, de and fr.
  • A combination of different languages and regional variations.

You can use hreflang tags to target different markets that use the same language. This is a fairly common use case. Using hreflang tags you can differentiate between the US and the UK, or between Germany and Austria.

9_Use_Hreflang_FI (1)

What’s the SEO benefit of hreflang?

So why are we even talking about hreflang? What is the SEO benefit? There are two main reasons, from an SEO point of view, why you should implement it.

First and foremost, if you have a version of a page that you have optimized for the users language and location, you want them to land on that page. Having the right language and location dependent information improves their user experience and thus leads to fewer people bouncing back to the search results. Fewer people bouncing back to the search results leads to higher rankings.

The second reason is that hreflang prevents a duplicate content problem. You might have the same content in English on different URLs aimed at the UK, the US and Australia. The difference on these pages might be as small as a change in prices and currency. Google might not understand on its own what you’re trying to do and see it as duplicate content. With hreflang you make it very clear to the search engine that it’s (almost) the same content, just optimized for different people.

What is hreflang?

hreflang is code, which you can show to search engines in three different ways, more on that below. With this code you specify all the different URLs on your site(s) that have the same content. These URLs can have the same content in a different language, or the same language but targeted at a different region.

What does hreflang accomplish?

Who supports hreflang?

hreflang is supported by Google and Yandex. Bing doesn’t have an equivalent, but does support language meta tags.

In a complete hreflang implementation, every URL specifies which other variations are available. When a user searches, Google goes through the following process:

  1. it determines that it wants to rank a URL;
  2. it checks whether that URL has hreflang annotations;
  3. it presents the searcher with the results with the most appropriate URL for that user.

The users current location and his language settings determine the most appropriate URL. A user can have multiple languages in his browser’s settings. I, for instance, have Dutch, English and German in there. The order in which these languages appear in my settings determines the most appropriate language.

Should you use hreflang?

Tip: homepage first!

If you’re not sure on whether you want to implement hreflang on your entire site, start with your homepage! People searching for your brand will get the right page. This is a lot easier to implement and it will “catch” a large part of your traffic.

Based on what we’ve learned on what hreflang is and how it works, we can determine if you should use it. You should use it if:

  • you have the same content in multiple languages;
  • you have content aimed at different geographic regions, but in the same language.

Whether the content you have resides on one domain or multiple domains does not matter. You can link variations within the same domain but can also link between domains.hreflang: the ultimate guide

Architectural implementation choices

One thing is very important when implementing hreflang: don’t be too specific! Let’s say you have three types of pages:

  • German
  • German, specifically aimed at Austria
  • German, specifically aimed at Switzerland

You could choose to implement them using three hreflang attributes like this:

  • de-de targeting German speakers in Germany
  • de-at targeting German speakers in Austria
  • de-ch targeting German speakers in Switzerland

However, which of these three results should Google show to someone searching in German in Belgium? The first page would probably be the best. To make sure that every German searching user who does not match either de-at or de-ch gets that one, change that hreflang attribute to just de. Specifying just the language is in many cases a smart thing to do.

It’s good to know that when you create sets of links like this, the most specific one wins. The order in which the search engines sees the links doesn’t matter, it’ll always try to match from most specific to least specific.

Technical implementation basics

Regardless of which type of implementation you choose (more on that below), there are three basic rules.

1. Valid hreflang attributes

The hreflang attribute needs to contain a value that consists of the language, optionally combined with a region. The language attribute needs to be in ISO 639-1 format (a two letter code).

Wrong region codes

Google can deal with some of the common mistakes with region codes, although you shouldn’t take any chances. For instance, it can deal with en-uk just as well as with the “right” en-gb. However, en-eu does not work, as eu doesn’t define a country.

The region is optional and should be in ISO 3166-1 Alpha 2 format, more specifically, it should be an officially assigned element. This means you need to use this list for verification. This is where things often go wrong: using the wrong region code is a very common problem. Use the linked lists on Wikipedia to verify that you’re using the right region and language codes.

2. Return links

The second basic rule is about return links. Regardless of your type of implementation, each URL needs return links to every other URL, note that it should point at the canonical versions, more on that below. The more languages you have the more you might be tempted to limit those return links: don’t. If you have 80 languages, you’ll have hreflang links for 80 URLs. There’s no getting around that. 

Optimize your site to the max: get all our SEO plugins and extensions at once! Get our Yoast Complete SEO bundle and save money! »

Yoast Complete SEO pack Info

3. hreflang link to self

The third and final basic rule is about self-links. Just like those return links might feel weird at some point, the hreflang link to the current page feels weird for some developers. It’s required though and not having it will mean your implementation will not work.

Technical implementation choices

There are three ways to implement hreflang: using link elements in the <head>, using HTTP headers or using an XML sitemap. Each has its uses, so we’ll discuss them and explain why you should choose any of these.

1. HTML hreflang link elements in your <head>

The first method to implement hreflang we’ll discuss is HTML hreflang link elements. To implement hreflang using header link elements, you add code like this to the <head> section of every page:

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

As every variation needs to link to every other variation, these implementations can become quite big and lead to performance issues. If you have 20 languages, choosing HTML link elements would mean adding 20 link elements as shown above to every page. This means adding 1.5KB on every page load, that no user will ever use, but will have to download. On top of that, your CMS will have to do several database calls to generate all these links. This markup is purely meant for search engines. That’s why I would not recommend this for larger sites, as it adds far too much, unneeded, overhead.

2. hreflang HTTP headers

The second method of implementing hreflang is through HTTP headers. HTTP headers are the solution for all your PDFs and other non-HTML content you might want to optimize. Link elements work nicely for HTML documents, but not for other types of content as you can’t include them. That’s where HTTP headers come in. They should look like this:

Link: <>; 
rel="alternate"; hreflang="es", 
rel="alternate"; hreflang="en", 
rel="alternate"; hreflang="de"

The problem with having a lot of HTTP headers is similar to the problem with link elements in your <head>: it adds a lot of overhead to every request.

3. An XML sitemap hreflang implementation

The third option to implement hreflang is using XML sitemap markup. It uses the xhtml:link attribute in XML sitemaps to add the annotation to every URL. It works very much in the same way as you would in a page’s <head> with <link> elements. If you thought link elements were verbose, the XML sitemap implementation is even worse. This is the markup needed for just one URL with two other languages:

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

You can see it has a self-referencing URL as the third URL, specifying the specific URL is meant for en-gb, and it specifies two other languages. Now, both other URLs would need to be in the sitemap too, looking like this:

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

As you can see, basically we’re only changing the URLs within the <loc> element, as everything else needs to be the same. This way, each URL has a self-referencing hreflang attribute, and return links to the appropriate other URLs.

XML sitemap markup like this is very verbose: a lot of output is needed to do this for a lot of URLs. The benefit of an XML sitemap implementation is simple: your normal users won’t be bothered with this markup. This has the benefit of not adding extra page weight and it doesn’t require a lot of database calls on page load to generate this markup.

Another benefit of adding hreflang through the XML sitemap is that it’s usually a lot easier to change an XML sitemap than to change all the pages on a site. No need to go through large approval processes and maybe you can even get direct access to the XML sitemap file.

Other technical aspects of an hreflang implementation

We’re going to assume that you’ve decided which type of technical implementation you’re going to choose. There are a couple of other technical specificities you should know about before you start implementing hreflang.

hreflang x-default

There is a special hreflang attribute value that’s called x-default. The x-default value specifies where a user should be sent if none of the languages you’ve specified in your other hreflang links match their browser settings. In a link element it looks like this:

<link rel="alternate" href="" 
  hreflang="x-default" />

When it was introduced, it was explained as being for “international landing pages”, ie pages where you redirect users based on their location. However, it can basically be described as the final “catch-all” of all the hreflang statements. If the users location and language didn’t match anything else, that’s where they will be sent.

In the German example we mentioned above, a user searching in English still wouldn’t have a “fitting” URL. That’s one of the cases where x-default comes into play. You’d add a fourth link to the markup, and end up with these 4:

  • de
  • de-at
  • de-ch
  • x-default

In this case, the x-default link would point to the same URL as the de one. We would not encourage you to remove the de link though, even though technically that would create exactly the same result. In the long run it’s usually better to have both as it specifies what language that de page is in and makes the code easier to read.

hreflang and rel=canonical


If you don’t know what rel="canonical" is, read this article!

rel="alternate" hreflang="x"markup and rel="canonical" can and should be used together. Every language should have a rel="canonical" link pointing to itself. In the first example, this would look like this, assuming that we’re on the homepage:

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

If we were on the en-gb page, not all that much would change other than the canonical:

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

Don’t make the mistake of setting the canonical on the en-gb page to, as this breaks the implementation. It’s very important that the hreflang links point to the canonical version of each URL. These systems should work hand in hand!

Useful tools when implementing hreflang

If you’ve come this far, you’ll probably be thinking “wow this is hard”, I know I thought that while learning about the topic. Luckily, there are quite a few tools available for people who dare to start implementing hreflang.

hreflang tag generator

hreflang tag generator tool by Aleyda

Aleyda Solis, who has written quite a lot about this topic too, has created a very useful hreflang tag generator that helps you generate link elements. Even when you’re not choosing for a link element implementation, this can be useful to create some example code.

hreflang XML sitemap generator

The Media Flow have created an hreflang hreflang XML sitemap generator. You can feed it a CSV with URLs per language and it creates an XML sitemap. A very good first step when you decide to go this route.

The CSV file you feed this XML sitemap generator needs columns for every language. If you want to add an x-default URL to it as well, just create a column called x-default.

hreflang tag validator

flang - hreflang validator tool by Dejan SEO

Once you’ve added markup to your pages, you’ll want to validate that markup. If you choose to go the link element in the <head> route, you’re in luck, as there are a few validator tools out there. The best one we could find is flang, by DejanSEO.

Unfortunately, we haven’t found a validator for XML sitemaps yet.

Become a technical SEO expert with our Technical SEO 1 training! »

Technical SEO 1 training Info

Keeping hreflang alive: process

Once you’ve created a working hreflang setup, you need to set up processes. It’s probably also a good idea to regularly audit your implementation to make sure it’s still set up correctly.

Make sure that people in your company who deal with content on your site know about hreflang. This makes sure they won’t do things that break your implementation. Two things are very important:

  1. When a page is deleted, check whether its counterparts are updated.
  2. When a page is redirected, change the hreflang URLs on its counterparts.

If you do that and audit regularly, you shouldn’t run into many issues.


Setting up hreflang is a cumbersome process. It’s a tough standard with a lot of specific things you should know and deal with. This guide will be updated as new things are introduced around this specification and best practices evolve, so check back when you’re working on your implementation again!

Read more: ‘rel=canonical: what is it and how (not) to use it’ »

31 Responses to hreflang: the ultimate guide

  1. Daniel McClure
    By Daniel McClure on 14 April, 2016

    Thanks for sharing this. Wondering if the SiteMap integration is something that would be covered by the Yoast SEO plugin yet?

  2. Jens
    By Jens on 12 April, 2016

    Great post Joost.

    You have a .com and plan to launch a .de. Given that you make the setup 100% correct, will the link-authority that .com has gained be “reused” at .de? Or will .de have zero authority from the beginning?

    Thanks again, I really hope that you will have time to reply.

  3. Francesco
    By Francesco on 11 April, 2016

    Ciao Yoost,
    Mad props for this article.
    I’m running an existing website hreflang= it and I’m gonna create a second version, using a different top domain: hreflang= en (without regional specification), with the same structure and contents.

    1) In you opinion, is the xml sitemap method convinient for this case?
    2)Rel=canonical is needed in this case and, if yes, how can I implement it? Maby through the Seo Meta Box in the single contents?

    Many thans for your help!

  4. Jaap Kuiper
    By Jaap Kuiper on 8 April, 2016

    Het gedeelte over canonical is mij helaas niet helemaal duidelijk. Als je 2 duitse versies hebt dan kan er toch maar 1 daarvan canonical zijn omgeacht op welke van de versies je aan het kijken bent? Even met een stukje uit dit artikel:

    Als je in dit voorbeeld op kijkt dan zou de canonical toch nog steeds naar moeten wijzen? Is canonical niet een methode om te zeggen dat je duplicate content hebt en dat je aangeeft welke versie het ‘origineel’ is?

  5. Jaap Kuiper
    By Jaap Kuiper on 8 April, 2016

    Hallo Joost, dit is een geweldig artikel maar ik heb toch nog een prangende vraag over targeting. Als je een domein heb met 3 engelse versies die allemaal identiek zijn (op de currency na). Een versie voor Engeland (pond), een versie voor Europa (euro) en een versie voor de rest van de wereld (dollar). Voor Engeland is het dan eenvoudig hreflang=”en-GB”. Voor de wereld zou ik hreflang=”en”. Maar dan blijft Europa over en ik gok er op dat ik die niet óók hreflang=”en” mag geven, klopt dat? Is er een workaround voor zo’n situatie?

  6. Darius
    By Darius on 8 April, 2016

    Hey Joost,

    Thanks for the great article!

    Does the Yoast SEO Plugin (free version) take care of these aspects (e.g. multilingual sitemaps, x-default, etc.)?

    We are using WPML and would love to have it work just perfect together with your plugin.

    Thanks a lot in advance!

    • Joost de Valk
      By Joost de Valk on 8 April, 2016

      WPML does that actually, we don’t :)

  7. Michelle
    By Michelle on 8 April, 2016

    This is a great guide, hreflang tags are so important for international sites. It’s surprising how often they are missed or implemented incorrectly, using ‘en-uk’ instead of ‘en-gb’ or no return tags for instance.

    Deepcrawl is able to validate hreflang tags in an xml sitemap. It’s not free but it’s a fantastic tool especially if you have a large amount of hreflang tags to check, we’ve found it really useful.

  8. Mitch Rezman
    By Mitch Rezman on 8 April, 2016

    Greetings Joost

    I am your newest disciple – just acquired my first two word press blogs – I am hand migrating 1500 pages from a proprietary host to one of them. I’ve just installed premium Yoast SEO – thank you for that plug-in. Now that I’m done blowing smoke I’m going to ask a small favor regarding 6,741 Hreflang Tags with Errors.

    I like building Frankenstein’s

    so my current website speaks six languages including English courtesy of They offer machine translation and I have five subdomains in five languages sitting under my parent domain

    6,741 Hreflang Tags with Errors looks like this in Google webmaster tools I should ignore those errors because they are handling Hreflang Tags by proxy on the server side.

    I’ve been operating e-commerce sites since 2003 – this particular issue is opaque to me – should I or should I not worry about these errors?

    Your input would be most welcome


  9. Yosh
    By Yosh on 8 April, 2016

    Hi, I installed my WordPress in English in order for other people to access it but my target country is Japan( I want to keep my site pretty simple and included a few Japanese and English contents so think don’t need to create language specific target pages.

    Then, I used another plugin to simply set up hreflang to ja since I don’t see any option in Yoast, actually don’t know how to implement it. However, in my Google Search Console International Targetting, it still shows “Your site has no hreflang tags.” It’s been like that more than a week whereas other data has been already coming in. Yoast plugin actually seems overriding another one???

    Please let me know how to fix this. Thank you.

  10. jasa seo
    By jasa seo on 8 April, 2016

    I’ve been using hreflang way since the first release, but do not yet know full hreflang

  11. Joseph
    By Joseph on 8 April, 2016

    Thanks for the great article. I have one question I’ve been struggling to answer. If you have multiple sites linked with HREFLang in the head of each page (say a US site, JP site, etc), is it redundant for each site to have a sitemap?

  12. Juan Carlos
    By Juan Carlos on 8 April, 2016

    Hello, I follow the hreflang XML sitemap one month ago, and verifying with the website you share, it appears “We can’t found link on alternate location” in the alternative URL.
    In the other link that MAX PRIN share, it says “Default language tag not existing (es)”. Please help me to know which is the problem.
    I am using for the design of the website, and I uplad the sitemap with the name “sitemap_hreflang.xml” outside the wp folder (direct inthe public.html)

  13. Beth Nicol
    By Beth Nicol on 7 April, 2016

    I use MultilingualPress which uses this functionality. Unfortunately, since SEO 3.1, I can no longer have both SEO and MultilingualPress active on my site (the 3.1 update broke MultilingualPress); So, it’s good to read about just how it works — even if I have to make a choice between SEO and multiple language support. (Right now, I’m choosing multiple languages and looking for and SEO replacement.)

  14. Le Tim
    By Le Tim on 7 April, 2016

    My ‘.com’ website is in both UK English & French (most traffic coming
    through the English side of the site) and I would like to know under the
    paragraph ‘Technical implementation choices’ which of the 3 suggested routes to
    choices would be best? My feeling is the first option would be the easiest
    (HTML hreflang link elements in your ) – please advise.

    • Joost de Valk
      By Joost de Valk on 7 April, 2016

      With just two languages the overhead isn’t so bad so the first option is probably easiest indeed.

  15. Le Tim
    By Le Tim on 7 April, 2016

    My ‘.com’ website is in both UK English & French (most traffic coming through the English side of the site) and I would like to know under the paragraph ‘Technical implementation choices’ which of the 3 suggested routes to choices would be best? My feeling is the first option would be the easiest (HTML hreflang link elements in your ) – please advise.

  16. Alexander Grau
    By Alexander Grau on 7 April, 2016

    Great post just like the rel=canonical! It made me see some points to improve in my hreflang structure and helped me to finally see how to best implement to canonical tags.

    Keep up the great posts as it’s a great contribution to new SEOs like myself.

  17. Andreas Ostheimer
    By Andreas Ostheimer on 7 April, 2016

    I am not through with reading but wondering wheter there is an AND or an OR between those list-items “you have the same content in multiple languages;
    you have content aimed at different geographic regions, but in the same language.”

    • Joost de Valk
      By Joost de Valk on 7 April, 2016

      Google will always use the most specific applicable hreflang line.

  18. Alexandre Bertails
    By Alexandre Bertails on 7 April, 2016

    Note that Yandex would only support the “HTML hreflang link elements” method.

  19. Max Prin
    By Max Prin on 6 April, 2016

    Hi there,
    Really good guide!
    The following validator is also worth taking a look at as well:
    – checks HTML link elements, HTTP headers and XML sitemap annotations (and looks for duplicate entries)
    – works with relative URLs
    – warning if default language tag is missing
    – detects language on pages
    – you can export the results into a .CSV document
    Check it out!
    Thanks again for this great guide!

  20. Arne
    By Arne on 6 April, 2016

    Thank you for this great post!

    What would you suggest for a page, on a website available in multiple languages, which is specific for one language, should you add the “x-default” and the ISO code in the hreflang tags or no hreflang at all?

    • Joost de Valk
      By Joost de Valk on 6 April, 2016

      Give me some more data to base this on :) generally I’d say: yes. Implement it.

  21. Menachem Rosenbaum
    By Menachem Rosenbaum on 6 April, 2016

    Thanks for a great round up on the hreflang topic.
    I have used hreflang XML sitemap generator many times it is truly an amazing tool. I just wish they’d have the x-default tag built in automatically.
    If you add a column of x-default as suggested, you need to delete all the duplicate section for running the default url twice.

    • Joost de Valk
      By Joost de Valk on 6 April, 2016

      There’s no problem with having a URL show up twice!

      • Menachem Rosenbaum
        By Menachem Rosenbaum on 7 April, 2016

        I still don’t think having a url twice is what we call best practice

        • Joost de Valk
          By Joost de Valk on 7 April, 2016

          It’s absolutely not an issue and in this case it’s actually better for the long term: you might want to change your default at some point and forget about the specific language. I would call this a best practice and John Mueller, of Google, has said that too at recent events, so I think you’re overruled ;)

Check out our must read articles about Technical SEO