An Hreflang Implementation Guide: How to add and Implement Hreflang Tags

If you work with multilingual and/or multi-country sites, you can help Google to recognize your different sites pages language and country audiences though different configurations, that are recommended to align as much as possible to give consistent signals to Google about your international sites targeting:

  • By having language/locale specific URLs
  • Effectively localizing the Web content of each one of your versions to their targeted audience
  • Allowing the crawling of all pages versions (avoiding automatic redirects)
  • Using ccTLDs or sub-directories or sub-domains in gTLDs that are geolocated to their relevant country (by using the Google Search Console “geolocation” feature)
  • Using hreflang annotations to specify each page language and alternatively, also country target.   

Since hreflang annotations allow to specify the language and country value of each of your different Website versions pages and the relationship between them (which URL is the “alternate” version of another for a given language and country, also called “alternates URLs”) they give you maximum granularity and a direct way to signal your pages targeting to Google. 

Let’s see what are hreflang annotations, how do they work and how to effectively implement them while avoiding errors:

  1. What are hreflang annotations and why they’re important
  2. The hreflang annotations implementation How-To video 
  3. The hreflang annotations implementation Step by Step Guide 
    1. Assess the hreflang implementation need 
    2. Assess the hreflang implementation scope
    3. Choose the hreflang implementation method
    4. Specify and include the hreflang code
    5. Validate the hreflang implementation in a test environment before launch
    6. Troubleshoot the hreflang implementation after launch and monitor continuously
    7. Establish hreflang best practices guidelines to be followed whenever a new page is published

What are hreflang annotations and why they’re important? 

Hreflang annotations are tags that can specify the language and alternatively, the country targeting of each page, which is recommended to use in the scenario when you have many different language or country versions of the same page, shown through different URLs.

Hreflang Tags Values Taxonomy

Hreflang tags then facilitate Google to select the right page to show in different language and country search results, as well as to understand, that although there might be different URLs showing very similar content, they’re not actually duplicates, as they’re targeting different audiences in different countries that speak the same language, for example.

However, hreflang annotations implementation can become complex when working with a high number of languages and countries and with sites of millions of URLs, with enterprise level platforms that provide little flexibility to implement changes, or even in smaller environments but without much Web development support, that can end-up causing some common hreflang tagging issues that will later trigger errors. In fact hreflang implementation is mentioned as one of those SEO related implementations that are harder to execute while avoiding issues.  

To avoid hreflang annotations implementation issues in complex environments, it’s important to establish an hreflang tags implementation process that doesn’t only considers the required steps to include them based on the selected implementation method to minimize errors with the right hreflang values, but additionally sets an overall process, with different steps to maximize success at a continuous basis: from the identification of those international versions to prioritization in the hreflang annotations implementation, to the hreflang tags validation, continuous monitoring development of best practices that should be continuously followed.

The hreflang annotations Implementation How-To Video

How do you set up hreflang annotations? Where do you put hreflang tags? Which are the supported hreflang values? Watch this Crawling Mondays How-To video showing how to go through the main steps of the hreflang annotations implementation process:   


The hreflang annotations Implementation How-To Guide 

Since the implementation of hreflang annotations can face many challenges, here’s an in-depth step by step guide with examples, that address many of the most common hreflang annotations issues. Let’s go through it: 

How to Implement hreflang: Following a 6 Steps Hreflang Implementation Process Guide

1. Assess the hreflang implementation need 

Implementing hreflang annotations is only relevant when: 

  • You are targeting many countries or languages with different language or country focused Web URLs
  • You have pages parity across your language/country versions, featuring the same pages across them. Eg: same categories, same products, etc.

If this is your case, then the next step is to identify the scope and level of priority of your hreflang annotations implementation, since adding hreflang tags might not be a trivial task and you will want to maximize their SEO benefit: 

  • Which of your languages and/or countries versions are you going to specify?
  • Which of their pages have indexable versions across more than one of them, that will need to be annotated?

To identify this better, is fundamental to ask:

Do you have pages which you have parity, attracting rankings or organic traffic from other languages or countries for which you have specific indexable URLs versions for? (eg: You have a laptop section for both the US and UK but the page ranking in the US search results is the UK version)

If you don’t have this issue and all your rankings and organic traffic are going to their relevant language/country URLs, then you *can* implement hreflang as a preventive measure across all of the indexable pages that have an alternate indexable URLs in other language or country versions (to avoid the above mentioned issue), but might not be a priority as its current impact will be none or low. It’s then important to assess the required effort and prioritize accordingly vs. other SEO actions of your SEO process.

On the other hand, if you do have this issue, it would be important to prioritize the implementation of hreflang in those pages attracting rankings/organic traffic from non-relevant countries/languages versions for which you have a specific indexable page version for, along their indexable language/country alternates.

Here’s a “should I implement hreflang” flowchart going through these questions and validation:


2. Assess the hreflang implementation Scope

An easy way to identify if you’re already attracting organic search traffic and rankings from non-relevant countries -for which you already have other relevant Web versions that are properly translated and geolocated through the other configuration settings discussed above- is through the “countries” segment of the Google Search Console “Performance” report.

To facilitate this analysis I’ve created this Google Data Studio Dashboard using the Google Search Console data that can easily help you to identify for free if your site versions are suffering from international search results overlay issues.

This Google Data Studio dashboard allows you to select (1) a site version to check (whether a cctld, subdirectory or subdomain, for example, your /gb/ version) that you have set as a property in Google Search Console. You should then select the date range to do the analysis for (2). Here you’ll be able to see which are the top countries for which the selected Web version is ranking for, and see if there are non-relevant countries for which you have already also specific versions generating non-trivial impressions and clicks.

Top countries you're ranking for

If you see that there are non-relevant countries (that you’re already targeting with other Web versions) generating non-trivial impressions and clicks, it’s recommended to analyze further by selecting them from the “non-relevant countries” drop down, from where you can select up to 3 different non-relevant countries to check at the same time, for which you’ll be able to see which are the top pages attracting more search visibility from them.

Assess and prioritize those important pages from a business, marketing, user experience and SEO standpoint that are attracting more clicks and impressions from these non-relevant countries, especially those that you know that you’re already properly targeting from the relevant country Web version, that will have a higher impact to fix.

Top Pages attracting impressions and clicks

Finally, you can further check which are the top queries generating those “non-relevant” rankings for these previously identified top non-relevant pages that you should select from a “top pages” drop down: are these relevant, meaningful queries for your business that are already targeted by the relevant Web version with pages?.

If so, this will additionally help you to not only prioritize their implementation (and later on, to monitor them), but also identify potential issues in the meant to be ranked pages in case you already have hreflang annotations in them but are still not correctly shown in the relevant search results markets for these terms, due to a lack of relevance, for example.

Top Queries for which The pages are Ranking For

Click here to copy and use the International Search Results Overlay Google Data Studio Dashboard.

Something similar can be also done by checking third-party ranking indexes like the ones of SEMrush, Ahrefs and Sistrix, -if you have access to them-that will show the terms for which your different international Web versions are ranking across all the countries they support.

In some cases these might be non-relevant queries or terms that you’re not targeting and don’t want to target with the Web content that you have for those countries, however, in others you might identify that you’re already targeting some additional relevant terms with non-relevant Web versions.

This analysis will help you to identify those set of languages and countries pages that need to be prioritized to use hreflang tags based on the identified international misalignment issues they already suffer from in Google’s search results.

As a result it’s recommended to create a list with all of the URLs for the different languages and country versions that you want to specify with hreflang attributes, making sure to also add their other countries and languages URLs alternates, as shown in the example below.


3. Choose the hreflang implementation method

After establishing the pages to specify with hreflang, you can then assess the best fitting hreflang implementation method following Google’s hreflang specification: whether by including hreflang through tags in the HTML head, by using XML sitemaps, or via the HTTP header.

Although Google will take into consideration any of these supported hreflang implementation methods it’s recommended that you select the one you want to use based on your site and project requirements as well as restrictions and be consistent with it to facilitate its validation, management and continuous updates.

Each of the hreflang implementation methods have pros and cons:

  • Hreflang tags in the HTML head

    It’s better to use this method in sites with a small number of languages and/or countries versions to tag, when using a platform that easily allows to add and edit the tags in the pages html head.
  • Hreflang in XML sitemaps

    XML sitemaps are usually the best method to use with bigger sites with many languages/countries versions which can end-up being too complex to specify in the HTML head, as doing it so would add too many extra lines of code, increasing the page size. This is also the best alternative whenever there’s no way to edit the HTML head to add the hreflang tags there.
  • Hreflang in HTTP header

    It’s better to leave this method when specifying hreflang for non-HTML documents like PDFs, DOCs, etc. as it is easier to be overlooked and can be more difficult to validate.  

If it’s not possible to use a single hreflang implementation method for all the Website pages as they might have different characteristics and can be generated through different platforms (for example, main site pages vs. blog posts), it’s important to establish clear rules of when one is used vs. the other, and avoid overlaying them, as it would make it harder to avoid errors or misalignments between them. 

4. Specify the hreflang tags code pattern

After deciding the best hreflang implementation method to use in your case, the next step is to avoid non-supported placements, tags, attributes or values, by having as a reference Google’s official specification, in order to annotate each one of the relevant pages versions with their language and alternatively, also country value while referring to their alternate versions for which their language and alternatively country value should be also specified, and which should specify back too, as shown below:

It’s fundamental that we only specify the hreflang annotations in indexable URLs, which also specify as alternates to other also indexable URLs, avoiding to do it so with redirected, error, non-indexed or canonicalized URLs.

It’s especially important to highlight how the to be included pages in the hreflang annotations should be self-canonicalizing too, as it’s a very common doubt/question to have: Do the URLs that are included in the hreflang annotations canonicalize to just “one” as their “original”? The answer is no, each one of these URLs are their own unique indexable pages targeted whether to different language or country audiences, and therefore, they need to be indexable and self-canonicalize.

Start by obtaining the hreflang code “pattern” to be used, understanding the syntax to be followed and where it should go in each case based on the chosen method, if it should be placed in the HTML head or to be included in XML sitemaps.

Supported hreflang values

Google formally uses the ISO 639-1 format for the hreflang language values and the ISO 3166-1 Alpha 2 for the regions, so it’s also important that you verify using these ISO specifications which are the values that you should use for each one of your targeted markets and include them as attributes as described in Google’s hreflang specification based on the selected implementation method.

Additionally, if you have a language or country version (or a “global”, generic one) that should be used as the “default” or fallback for non-specifically targeted countries or languages visitors, you can also use and specify these URLs with the “x-default” value, as described by Google here too.

In case you don’t have a specific Website version targeted to be the “global” version of your site as a “default” one, you can specify any of the existing ones, such as you English or US version to be the “default” and assign to those URLs also the “x-default” value, which is relatively common to do so. So for example, if you only have a US and UK version both in English, but don’t have a specific one for Australia, you might want to choose one of them to show to Australians by default, since you don’t have a specific version for them yet.

Common hreflang tags values errors

There’s no issue by assigning multiple hreflang tags with different values to URLs, as long as they’re actually relevant, Eg: Don’t assign a language value that is not really the relevant one for the page, if you specify that a page language is in French through the hreflang annotation value, when its content is actually in English, it’s incorrect and it won’t make it rank for French queries anyway.

It’s also important to note that another of the most common hreflang implementation issue comes from not adding the supported language and country values, or including values for region types that are not supported at all, like continents: Google doesn’t support targeting towards Europe or Asia, for example and therefore there’s no way to specify continents directly through hreflang values (“eu” is not an officially supported value, for example); and although there might be domain extensions for continents, like .eu or .asia, they are also treated as generic domains by Google too. 

In the case that although not ideal, you need to work with “continent” targeted URLs versions, then what you can do is to assign them the value of each of the individual countries that they should target, for example, if you have a “European” version with a URLs like: in English, then you can assign to the pages under this version the values of the English language along all of the countries that are targeted by this version individually: The UK, Ireland, France, Germany, Spain.

This is just a “workaround” to allow Google to better understand in which country scenario it should show those pages, because realistically, the search traffic potential that a page in English can attract from non-native English Speaking countries in Europe like France, Germany and Spain in most scenarios will be trivial, with a few exceptions (like some travel or jobs related scenarios).

Generating the right hreflang tags

To avoid hreflang attributes or tags codes errors, I created a free hreflang code generator tool that can be used to obtain the hreflang values and code to use as a pattern in your Website HTML templates or XML sitemaps, so you can then replace with each of your site pages URLs.  

The tool will allow you to generate the hreflang annotations based on the selected implementation method, including the relevant values for each one of your languages/countries versions, that you can generate for your main site URLs and then use to expand the implementation to all of the relevant pages, by replacing with the URLs; or use as a pattern/reference to send to the Web development team so they can implement it through the Website platform:

If you have a big, complex Web structure with many international Web versions that are difficult to map then I’d recommend that you take a look at enterprise level hreflang generators such as the HREFlangbuilder, that will allow you to implement hreflang annotations via XML sitemaps at a large scale with high flexibility.

Additionally, it’s worthy to note how if you’re using a popular CMS, there will be likely multilingual / multicountry plugins  or extensions supporting the hreflang tags implementation in all of your pages, for example, for:


WordPress multilingual plugins like Polylang and WPML plugin for WordPress that will help you to enable multi language or country versions of your site support hreflang tags implementation through the HTML head, and allow you to also modify the values included in each case, as can be seen below:

It’s important to always revise though if the values are the relevant ones since as shown above, since in the case of WPML for WordPress, it was adding the US country value to the English language pages by default, however, the English version of the site is actually targeting all English speakers, not only US ones, so this was modified by replacing the “en-us” value to only the “en” one, in the “hreflang” fields from the language configuration section.


A similar functionality is offered by the Mageworx Magento 2 SEO extension, that allows to specify in which types of pages they should be included (for category pages, product pages, etc.), as well as values depending on the language and country that you’re targeting. 


In the case of Shopify, hreflang can be implemented via multilingual extensions like Weglot, but can be also added by editing the theme.liquid layout page to include the hreflang tag to point to each language/country version canonical URLs. 

For this you should go to the Shopify admin “Online Store”, and then under “Themes” go to “Actions” and then “Edit code”, opening the “Layout” folder to find and add the hreflang code in the head area of the “theme.liquid” file, like this, for a US and Australian sites used as examples:

<link rel=”alternate” href=“{{ canonical_url | replace: shop.domain, ‘’ }}” hreflang=”en-us” />
<link rel=”alternate” href=“{{ canonical_url | replace: shop.domain, ‘’ }}” hreflang=”en-au” />


5. Validate the hreflang annotations implementation in a test environment before launch

As with any other SEO related execution, it’s recommended that hreflang annotations are first implemented in a test environment to crawl and validate them before their release.

You can use SEO crawlers like Deepcrawl, Sitebulb, Screaming Frog or Ryte, that include an international SEO section that includes hreflang validation, to crawl the relevant set of pages where the hreflang has been implemented (whether doing a site or XML sitemap crawl) to identify any potential errors, verifying the existence of the correct hreflang annotations in every relevant page, the inclusion of a return tag, the usage of the correct values for every page, etc.

Hreflang validation - Crawlers

6. Troubleshoot the hreflang tags implementation after launch and monitor continuously

As soon as you launch the hreflang annotations, recrawl your site, making sure to include all of the relevant pages of the different international versions where hreflang has been implemented, to identify and fix any potential change that might have happened during the release and could cause issues in the live site that you couldn’t have identified before, checking in particular the following very common errors: 

  • The pages are showing the right language and alternatively, country value (eg: you’re not tagging the US pages with the Australian value)
  • The pages are referring to relevant URLs as alternates for the other languages and/or countries (eg: you’re not tagging as “alternate” of your home page in English, the about us in Spanish, but the relevant home page in Spanish)
  • The language and/or country value are the correct one (eg: you’re not adding “en-uk” for English in the UK, but the supported values which are “en-gb”)
  • The pages that you’re adding in the hreflang annotations are indexable (eg: the URLs are not redirected, triggering errors, adding a meta robots noindex tag, are canonicalized to other URLs, etc.)

You can also validate individual set of pages with the following free hreflang validation tools:

After fixing any remaining issues you should start monitoring the hreflang implementation at a continuos basis through the Google Search Console International Targeting report to identify any remaining problems.

Hreflang errors shown in the international targeting “language” report are grouped by those found in pages belonging to the same languages/countries versions, -for example, the US in English pages or the Spain in Spanish pages with problems-, and then by type of error found in each language/country version -such as the “no return tags” when the URLs of an alternate page is not found (as it’s showing an error http status, redirected, etc.), or “unknown language codes” when a non-supported value has been added-, showing first those with the highest number of issues. It’s then recommended to start the troubleshooting directly with those language/country versions showing directly the highest number of problems.   

Additionally, to facilitate the source of the issues, when selecting each type of error identified in each language/country version, you’ll be able to see which are the affected pages, showing up to a 1,000 URLs, paired with their alternates URLs affected by the issues.

Because of this when implementing hreflang annotations through XML sitemaps it’s highly recommended to generate them following certain organization criteria that facilitates the identification of URLs in them, in case there are issues and a need to spot and change them. For example, following a hierarchical organization: by country, language, category, etc.  

Something similar should be also done to identify any potential new languages and countries search results misalignment issues in Google’s Search Results via the Google Search Console Search Analytics or the new Performance report and ranking indexes like SEMrush, Sistrix or Ahrefs -that were shown above-.

The same can be also done by validating the language and country source of every international site through Google Analytics “Geo” Report, to verify that there’s no organic traffic coming from non-relevant ones, and if so, to identify which pages are attracting the traffic and if these pages have a relevant alternate, making sure that they are specified with the hreflang annotations.

Besides the post-launch validation, it’s also fundamental to continuously monitor the hreflang implementation: Setting frequent crawls to identify any hreflang annotations changes that can happen when there are new Web releases or changes, monitoring via the Google Search Console and additionally, setting real time alerts.

To identify and be alerted in real time whenever hreflang annotations changes happen it’s advisable to use and configure tools like Contentking or Little Warden, that you can set to warn you whenever hreflang tags are changed in your top or a subset of your most important pages. Contentking supports changes implemented via XML sitemaps too.

You can also configure the alerts to be sent to your email or directly to your project management system so you can take action fast.

hreflang alerts with contentking

7. Establish hreflang implementation best practices guidelines to be followed whenever a new page is published

Last but not least, after launching the hreflang annotations, it’s critical to document all the steps that have been followed in the implementation process so they can serve as a reference and establish hreflang tags best practices based on them, to follow certain hreflang execution steps and criteria whenever a relevant page of the site versions within the hreflang implementation scope is eliminated, changed or published, considering aspects such as: 

  • Which international versions were included/excluded in the hreflang annotations and why?
  • Which pages of those international versions were included/excluded from the hreflang implementation and why?
  • Which hreflang implementation method was chosen and why?
  • Which tools were selected to generate, test and monitor hreflang annotations and why?
  • Which new pages should include hreflang annotations and what should be the implementation method?
  • When and where the hreflang implementation should be tested before any release?
  • Who should specify, implement, validate and approve any hreflang related work?
  • How often hreflang annotations should be checked and who will be in charge to fix any new identified issue?
  • etc.

Asking and documenting these and similar hreflang execution questions can help establish the “hreflang tags implementation guidelines” within the organization, as well as a hreflang execution checklist that can be taken into consideration in the Website development process at a continuous basis.

By following this hreflang tags implementation process that considers the most critical decisions related to their execution and maintenance you’ll be able to have a cost-effective hreflang implementation process that effectively specifies your targeted languages and/or countries while also minimizing hreflang errors, especially in bigger Websites with many languages and countries versions. 

If you found this hreflang guide useful, you might also find the following interesting: