Hreflang Attribute 101

Luke Harsel

Jun 21, 20199 min read
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. 

Hreflang is a need-to-know attribute for those concerned with the SEO of an international website.

Where Does An Hreflang Tag 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 head of the page

  2. In the HTTP header (for non-HTML files like PDFs)

  3. On the XML sitemap

The hreflang attribute looks like:

rel="alternate" href="(URL)" hreflang="(language and country code)"

  • rel="alternate" – Similar to the rel="canonical" tag, this is code that tells search engines there is another version of this webpage. 

  • href= – The URL that follows href= is the location of the specified page. 

  • hreflang= – The hreflang attribute specifies the country and language of the alternate page. Use language and country codes to dictate which webpage to show. 

Language codes need to follow the two-letter code style of ISO 639-1 when written in the tag. For example, en (English), es (Spanish), zh (Chinese). 

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 format — for example, au (Australia), us (United States), sg (Singapore).

When writing the hreflang tag, always place the language code first, followed by the country code. For example, en-au, es-us, zh-sg.

For example, if the webmaster of 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="" hreflang="en-us" />

<link rel="alternate" href="" 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="" hreflang="es-ve" />

<link rel="alternate" href="" hreflang="es-mx" />

These tags were generated using the hreflang tags generator on Try it yourself if you would like an extra hand getting this right.

Pro tip: Remember there is a difference between the <head> and <header> elements. The <head> area should contain information that shouldn’t be shown on the page. This is where to place your hreflang attribute. A <header> tag tells a bot or screen reader the content it is wrapped around should be considered the introductory portion of a page or section.

  1. 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. Despite the name, this has nothing to do with the on-page <head> or <header> HTML tags but is set in the backend of a site.

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: <>; rel="alternate"; hreflang="en", <>; rel="alternate"; hreflang="fr"

  1. On The XML Sitemap

The third suggested way of implementing hreflang onto a website is through the sitemap.xml. There is a great Google support article that provides detailed instructions.

Highlights: Some Other Hreflang Topics We Will Cover

  • Common Mistakes And Troubleshooting

  • Some Things To Know Before Implementing Hreflangs

  • Why Hreflang Attributes Should Be Used

  • Reasons For Not Using Hreflang

Common Mistakes And Troubleshooting

Our team published a study on the most common hreflang mistakes, and for a long time, Aleyda Solis’ Search Engine Land column on auditing hreflang issues has been a go-to resource for many to get this right, especially when dealing with multiple languages and regions.

Typos And Underscores

Both of the aforementioned pieces cite the fact that simple typos in the language or country code are very common mistakes 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. Although, a 2017 tweet exchange involving Google Webmaster Trends Analyst Gary Illyes indicates that it should not cause Google too much trouble if you get it wrong – in theory, at least.

Although there is also thought to be some wiggle room for switching GB and UK as country codes (because Google is pretty smart), you absolutely should aim to use ISO 639-1 format to show language. If you use an incorrect abbreviation (like eng instead of en, for example), Google will likely ignore it, and your code might not work.

Not Using Self-Referencing Hreflangs

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.

Neglecting Bing

Lastly, if you want your international website to work on Bing, you will have to follow their separate guidelines. There is a Bing Webmasters article that will teach you how to tell Bing your website’s language and country code, but it appears to be out of date as the http-equiv=”content-language” meta tag it suggests is considered bad practice since HTML5.

Instead, the prevailing wisdom is to specify the language of a page using lang=, and to indicate the intended audience with a Content-Language header.

Some Things To Know Before Implementing Hreflangs

Google Could Ignore You

To Google, at least, hreflang annotations have been known to be regarded as signals, not directives. In other words, Google may ignore them. It should do the trick, but it is not a cast-iron guarantee.

Consider A Language Code With No Country Code

There are other ways a user might end up pointed in the wrong direction, too. 

If you only state a URL for speakers of a language and living in your specified countries (e.g., en-us), but don’t dictate a URL for a user of that language but residing in a country you haven’t added a code for (e.g., an English speaker in Italy), Google will make a best guess. 

Meaning it could get it wrong. 

Consider adding a generic tag with a language code but no country. This generic hreflang="en" tag, for example, will help state to which version of a page an English-speaking user living in Italy should be sent.

There are quite a few other nuances when it comes time to implement hreflang tags. This video from Google is several years old but provides a good overview of things that can trip you up. It is definitely worth a watch.

Youtube video thumbnail

Don’t Want To Target Anyone? Use x-default

Using hreflang="x-default" is essentially a way of saying, ‘This URL doesn’t target any language – it is open to everyone.’ It is great for if a page caters to many languages or is a language selection page. It certainly beats adding tags for masses of languages.

Whether Or Not To Use Hreflang

Hreflang implementation can solve all kinds of regional and language issues. But that doesn’t mean it is always the right solution for you.

Why Hreflang Attributes Should Be Used

SEO Benefit: Solving Duplicate Content Issues

Perhaps the biggest boon when using hreflang is solving genuine duplication issues quickly and easily. A site split across multiple regional domains, subdomains, or subfolders targeted to different countries could be seen to have large proportions that are nearly or fully identical.

Consider that a brand could sell the same 100 things in the US, Canada, UK, Ireland, Australia but have unique URLs for each. 

That company then has an issue: does it write unique product descriptions, blogs, guides, and category pages for each market to avoid any negative effect on search performance caused by duplicate content? Or does it simply implement hreflang tags and save days’ worth of work?

User Benefit: Serving Better-Targeted Content

Perhaps you have gone to the effort to use British phrasing and spelling throughout the UK version of your site. You even have a few pop culture references the average US site visitor simply wouldn’t get. Hreflang tags can make sure users from the States don’t get confused and British users feel more at home.

Reasons For Not Using Hreflang

You Have Duplicate Content In Different Languages

Hreflang attributes won’t hurt, but they are not necessary to avoid duplicate content issues on pages that are direct translations of one another. 

Google still recommends you give its crawlers a hand by using hreflangs, but multiple versions of a page will not be regarded as duplicates so long as most of the content is translated. 

So, do not expect lots of hreflang implantation to save you from any detrimental effect on rankings because you probably don’t have to worry about it anyway in this instance.

You Want To Lock Google Searchers From Other Countries Out

If you want to be reasonably certain that only users from a single country will be served your site in Google’s results, hreflang is not necessarily the best answer. Instead, Google Search Console can provide a more foolproof, if less forgiving, option if you have a generic top-level domain, such as .com and not something like .ca.

Using the Country tab in the International Targeting report in Google Search Console, choose a target country, and tick the ‘Geographic target’ checkbox.

This might seem like a good idea. In fact, it might be a great idea if you are 100% sure you don’t want any organic search traffic from outside a single country. But do remember that Google will seek to exclude serving your site to anyone in another country, not simply better target searchers in your preferred region. 

Are you certain no one in another country, not even a national living on the other side of the world, will find your service or products useful and become a potential customer or client?

Perhaps you want to go the complete opposite direction to this. You can do the inverse of the above and select ‘Unlisted’ in the dropdown box associated with the ‘Geographic target’ checkbox. That way, your site won’t have any regional limits.

You Are Only Optimizing For Bing or Baidu

Yes, this does seem very unlikely for most Western websites, but it is possible. It is even probate in certain areas of the world.

As we touched on above, Bing doesn’t use hreflang tags to work out the preferred language and country of a page. And nor does Baidu, China’s preeminent search engine. 

You should specify language and intended audience on an HTTP header level if attracting an audience from China or optimizing Bing traffic is of particular interest to you. 


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!

Author Photo
Content Writer. 6+ years at Semrush. Helping you understand how to use our SEO tools to solve your marketing problems.