
Submit post
Go to Blog

Hreflang Attribute 101


Hreflang Attribute 101

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, https://www.semrush.com/blog/7-common-hreflang-mistakes-and-how-to-fix-them/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.


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!

Go global!

Hreflang implementation audit with SEMrush!

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.
Share this post



Occasionally takes part in conversations.

Superb Post. Thanks dude ,Nice explanation about all the possibilities for hreflang attribute .This is most important Ranking factor for International SEO. This always counter by robots ,crawler and spider all the available Search engine.

Either just recently joined or is too shy to say something.

luke can you explain me in detail say suppose if i have to publish multiple URL's for 10 languages how the html should be developed, for example can we develop an html like this?

Either just recently joined or is too shy to say something.

Excellent Post,

The Hreflang tag is used to explain the language and geographic market expected for a web page. A powerful solution for multi-market websites, Hreflang Sitemaps helps search engines to rank the right page in the right index.

There are many hreflang tools to create tag as per language and country you want the display.

Occasionally takes part in conversations.

Thank you for writing this article. Interesting reading. I need some help, however, if you'd be so kind.

I'm in Australia. I have a .com domain and wish to have posts directed at both US and AU visitors.
These posts would mostly be almost exact duplicates. (I use WordPress, btw)

I'm having trouble getting my head around the whole hreflang thing.

I've written a post (not yet published) and I'm unsure as to just how I show that this is the en-au version.
I edited the slug to https://"my domain".com/en.au."post title" but WP amended it to read en-au-"title"

Other than that, I can't see where or how I can edit the URL.

Maybe I'm missing something here. I'm no expert in the field and have searched to no avail so far.

I'd be grateful if you would give me a little advice on this.

Cheers, Thomas.
Luke Harsel

SEMrush employee.

Thomas Greenbank
Hey Thomas, thanks for reading and following up with your question!

It sounds like you are worried about how to write the URLs in order to direct the hreflang attribute correctly. If you want to have two urls for the two posts, something like "domain.com/us/post-title" and "domain.com/au/post-title" would be fine. You do not need to use periods or language and country codes in the URLs. The URLs just need to be unique for the purpose of organization.

The language and country codes come into play when you are adding the hreflang attribute to your tag (as a link inside the tag).

In this link is where you would specify your country code for the opposite post.

So in the english post, you would need:

and in the australian post:

Does that make sense? Really hope it helps you figure it out! If you have more followups, feel free to email me at [email protected]

Occasionally takes part in conversations.

Luke Harsel
Thanks, Luke.

I think I've got it now.

If I have two posts, one for au and one for us; do they need to have similar titles and/or slugs?

I'm guessing prob not, but I'd like to be sure.

Thanks again. Thomas.

Occasionally takes part in conversations.

Luke Harsel
Hey Luke.
Thanks largely to your input, I've finally come to grips with the proper implementation of hreflang tags.
So much so, in fact, that I wrote a post of my own aimed at helping other newbies stumbling in the dark to understand the issue. I'd appreciate your comments if you can spare a little of your time. my-buzz (dot com) /hreflang-tags-to-boost-your-rankings/
I hope I'm not breaking any rules by showing this link. My apologies if I have.
Once again, thanks for your help. Thomas.

An experienced member who is always happy to help.

Thanks for this, Luke! This is a nice and simple explanation to give to clients when you are mentioning the need for it in site audits and/or reports.
Luke Harsel

SEMrush employee.

Thanks for reading, George! Glad you find it useful.

Send feedback



Thank you for your feedback!