English Español Deutsch Français Italiano Português (Brasil) Русский 中文 日本語
Submit post
Go to Blog
Luke Harsel

Hreflang Attribute 101

The Wow-Score shows how engaging a blog post is. It is calculated based on the correlation between users’ active reading time, their scrolling speed and the article’s length.
Luke Harsel
Hreflang Attribute 101

What is the Hreflang Attribute?

Hreflang is an HTML <link> or <link> tag attribute that tells search engines the relationship between pages in different languages on your website. Google uses the attribute to serve the correct regional or language URLs in its search results based on the searcher’s country and language preferences. Concerning the SEO of an international website, hreflang is a need-to-know attribute.

Where does it go?

Google support tells us that the tag can be implemented in one of three ways (you only need to choose one). 

  1. As a link in the HTML header of the page

  2. In the HTTP header (if you publish non-HTML files like PDFs)

  3. On the sitemap

1. As a link in the <head> of the page

The hreflang attribute looks like

rel="alternate" href=”(url here)” hreflang="x"

...with “x” being where you would place the language and country codes that dictate which webpage to show. Rel=”alternate” (similar to the rel=”canonical” tag) is a tag that tells search engines that there is another version of this webpage, and the hreflang attribute specifies the country and language of the alternate page. Then, the URL that follows “href= “ is the location of the specified page.

Language codes need to follow the two-letter code style of ISO 639-1 when written in the tag. If you are simply translating a page in the same country, a country code is not needed.But, if you use a country code, it must follow ISO 3166-1 Alpha 2. When writing the hreflang tag, always place the language code first followed by the country code.

For example, if the webmaster of example.com wants to show her homepage to English speaking and Spanish speaking users in the United States, she would use the following annotations in the <head> of her site’s HTML:

<link rel="alternate" href="https://www.example.com" hreflang="en-us" />

<link rel="alternate" href="https://www.example.com/es" hreflang="es-us" />

If she wanted to show the homepage to Spanish speaking users in Venezuela and Mexico, the hreflang annotation would look like:

<link rel="alternate" href="https://www.example.com/ve" hreflang="es-ve" />

<link rel="alternate" href="https://www.example.com/mx" hreflang="es-mx" />

These tags were generated using the hreflang tags generator on aleydasolis.com. Go here to use it yourself.

2. In the HTTP header (if you publish non-HTML files like PDFs)

HTTP headers should be used to implement hreflang for PDFs and non-HTML content on your website. Yoast explains that the problem with using HTTP headers is that it can add a lot of overhead to every request made on your site, potentially slowing down the user’s browsing experience. 

Nevertheless, to identify a PDF document on your site in English and French versions, the link should appear in the HTTP header something like this:

Link: <http://en.example.com/document.pdf>; rel="alternate"; hreflang="en", <http://fr.example.com/document.pdf>; rel="alternate"; hreflang="fr"

3. On the Sitemap

The third suggested way of implementing hreflang onto a website is through the sitemap.xml. Read this Google support article for detailed instructions.

Problems & Troubleshooting

Our team published a study on the most common hreflang mistakes in February and in April Aleyda Solis wrote a column on Search Engine Land on the same topic.

Both publications cite the fact that simple typos in the language or country code are very common issues on international websites trying to implement hreflang.

Simple errors such as using an invalid country code, using a country code but missing a language code, or even using an underscore instead of a hyphen can render your hreflang attribute invalid.

This is why you absolutely need to use ISO 639-1 format. If you use an incorrect abbreviation (like eng instead of en, for example), Google will ignore it and your code will not work.

Another common issue is failing to add a self-referencing hreflang tag to the page. This means having an hreflang tag that references the language and country of the page itself in addition to identifying the other pages.

Lastly, if you want your international website to work on Bing, you’ll have to follow their separate guidelines. Read the Bing Webmasters article to learn how to tell Bing your website’s language and country code.


So, let’s wrap this up. Hreflang is a <link> tag attribute that helps search engines serve the appropriate version of a website to international web users. It will be important to use the correct language code and country code everywhere you implement the attribute on your website. If you want to audit your website’s use of the hreflang tag for any errors, be sure to check out the SEMrush Site Audit tool - there are multiple checks built in specifically for international SEO so you can start optimizing your global website!

Get a free 7-day trial

Start working on your online visibility

Please specify a valid domain, e.g., www.example.com

Luke Harsel

SEMrush employee.

I write articles on the SEMrush Knowledge Base and blog to show people how the tools on SEMrush can make it easier to participate in digital marketing. When I'm not at work I like to write music and spend time in nature.
Send feedback
Your feedback must contain at least 3 words (10 characters).

We will only use this email to respond to you on your feedback. Privacy Policy

Thank you for your feedback!