Table of content

  1. What is the benefit of hreflang?
  2. When to use the hreflang attribute?
  3. How to use the hreflang attribute?
    1. X-Default for non specified languages and countries
    2. Example: hreflang in HTML head
      1. Language + country targeting
      2. Language + country targeting + x-default:
      3. Multi language + multi region + x-default:
    3. Example: hreflang in HTTP header
    4. Example: hreflang in XML sitemaps
    5. Example: hreflang single domain and multi domain
    6. Supported language and region codes
  4. Common mistakes with the hreflang attribute
    1. No self reference used
    2. Hreflang always pointing to home page for language and region
    3. Link to URLs with non-200 HTTP status code
    4. Conflicting multiple hreflang definitions
    5. Conflicting hreflang and rel=canonical
    6. Incorrect usage of x-default
    7. X-Default myth: You cannot use one URL for localized and x-default alternate
    8. Not using absolute URLs
    9. Not using the right country and language codes
    10. Invalid syntax in country and language code annotations
    11. Using cacheable redirects for geotargeting
    12. Incomplete hreflang URL set - no return tags
    13. Conflicting hreflang and Google Search Console definitions
  5. How we help - Hreflang Checker

Hreflang Attribute - Target Languages and Regions - SEO Guide

Hreflang can help search engine spiders to understand how to handle multilingual or multi region websites. Hreflang is a link attribute defined by RFC 5988. It is also known as hreflang tag or rel="alternate" hreflang="x". This guide covers everything you need to know about hreflang.

What is the benefit of hreflang?

Hreflang offers opportunity to define

  • the language and region assigned to a particular URL
  • the default content version

The benefits of using hreflang are

  • search engines will more likely show the right localized content version
  • duplicate content issues with multilingual and multi-region websites can be avoided

When to use the hreflang attribute?

The hreflang attribute can be used in multilingual and multi-region site environments. These environments may run on a single host or can be distributed over multiple localized domains or subdomains.

The hreflang attribute can solve a number of possible issues:

  • Duplication or similar content due to targeting different markets with the same language
  • Duplication or similar content due to targeting different markets with different languages
  • Targeting issues due to targeting a country market with different languages
  • Wrong region specific data (e.g. prices, currency or address and date formats)

You should use hreflang to avoid duplication or similar content issues as well as issues with incorrect language or region targeting in search results for a multilingual and multi-region website.

How to use the hreflang attribute?

The hreflang attribute can be implemented in three ways:

  • HTML head
  • HTTP header
  • XML sitemaps

For every page you have, you define a set of URLs for all language and region targeting alternates. Every URL in the set must contain a link to every other URL in the set, including a link to itself. It is also suggested to define a default alternate.

X-Default for non specified languages and countries

The default alternate can be defined using the option 'x-default'. This default version is shown in search results if no targeted landing page is assigned to the user's region or language.

Note: you can also use the x-default version on a separate x-default URL that only detects the language and redirects the user to the proper language or region alternate of the content.

Example: hreflang in HTML head

The most common implementation of the hreflang attribute is the usage in the HTML head with the link tag.

Language targeting only:

<html>
<head>
<link rel="alternate" hreflang="en" href="http://example.com/page.html">
<link rel="alternate" hreflang="fr" href="http://fr.example.com/page.html">
</head>
<body>

This example contains targeting for the languages English and French.

It defines http://example.com/page.html as the page for the English speaking audience. The French alternate version is defined as http://fr.example.com/page.html.

Language + country targeting
<html>
<head>
<link rel="alternate" hreflang="en-CA" href="http://example.com/en-ca/page.html">
<link rel="alternate" hreflang="fr-CA" href="http://example.com/fr-ca/page.html">
</head>
<body>

This example contains targeting for English and French users in Canada. It defines http://example.com/en-ca/page.html as the page for the English speaking audience in Canada. The French alternate version for the canadian audience is http://example.com/fr-ca/page.html.

Language + country targeting + x-default:
<html>
<head>
<link rel="alternate" hreflang="en-CA" href="http://example.com/en-ca/page.html">
<link rel="alternate" hreflang="fr-CA" href="http://example.com/fr-ca/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">
</head>
<body>

This example is identical to the previous example. The only difference is there is a x-default defined. The URL http://example.com/page.html is defined as the x-default and tells the search engines to prefer this result for queries from outside Canada with any language or from inside Canada with another language than french or english.

Multi language + multi region + x-default:
<html>
<head>
<link rel="alternate" hreflang="de-DE" href="http://example.com/de-de/page.html">
<link rel="alternate" hreflang="de-CH" href="http://example.com/de-ch/page.html">
<link rel="alternate" hreflang="fr-CH" href="http://example.com/fr-ch/page.html">
<link rel="alternate" hreflang="it-CH" href="http://example.com/it-ch/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">
</head>
<body>

This example contains targeting for different countries that share the same language as well as different languages within one country. Additionally there is a x-default defined.

Example: hreflang in HTTP header

When you have to assign language alternates to non HTML documents, you can send the hreflang attributes with the HTTP header.

HTTP/1.1 200 OK
Content-Type: application/pdf
Link: <http://example.com/page.pdf>; rel="alternate";hreflang="x-default", <http://uk.example.com/page.pdf>; rel="alternate";hreflang="en-GB",
<http://us.example.com/page.pdf>; rel="alternate";hreflang="en-US"

Note: This method is not suggested for larger URL sets, as the HTTP header is sent without compression. You might also reach limits for the header length within some software e.g. web servers or proxy servers.

Example: hreflang in XML sitemaps

The hreflang alternates can also be defined in the XML sitemaps.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
    xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
    <loc>http://example.com/page.html</loc>
    <xhtml:link
                    rel="alternate"
                    hreflang="en-US"
                    href="http://us.example.com/page.html"
                    />
    <xhtml:link
                    rel="alternate"
                    hreflang="en-GB"
                    href="http://uk.example.com/page.html"
                    />
    <xhtml:link
                    rel="alternate"
                    hreflang="x-default"
                    href="http://example.com/page.html"
                    />
</url>
<url>
    <loc>http://us.example.com/page.html</loc>
    <xhtml:link
                    rel="alternate"
                    hreflang="en-GB"
                    href="http://uk.example.com/page.html"
                    />
    <xhtml:link
                    rel="alternate"
                    hreflang="x-default"
                    href="http://example.com/page.html"
                    />
    <xhtml:link
                    rel="alternate"
                    hreflang="en-US"
                    href="http://us.example.com/page.html"
                    />
</url>
<url>
    <loc>http://uk.example.com/page.html</loc>
    <xhtml:link
                    rel="alternate"
                    hreflang="en-US"
                    href="http://us.example.com/page.html"
                    />
    <xhtml:link
                    rel="alternate"
                    hreflang="x-default"
                    href="http://example.com/page.html"
                    />
    <xhtml:link
                    rel="alternate"
                    hreflang="en-GB"
                    href="http://uk.example.com/page.html"
                    />
</url>
</urlset>

Note:

  • Use the following namespace xmlns:xhtml="http://www.w3.org/1999/xhtml"
  • There must be an URL element for every URL in the set - For every URL element in the URL set, there must be all alternates defined
  • The URL itself needs to be defined in the URL set

The benefits of using XML sitemap hreflang definitions:

  • avoids bloating your HTML markup and HTTP headers
  • centralize hreflang definitions for all known URLs.

The disadvantages of using XML sitemap hreflang definitions:

  • If you cannot centralize the XML sitemaps in your multisite environment, it might make it a lot harder to maintain your hreflang alternates synchronized and up to date.
  • bloats your XML sitemaps

Example: hreflang single domain and multi domain

It is noteworthy that hreflang can be used over multiple domains, subdomains and folder structures, not only within one domain. This makes it an effective tool to organize your international website environment in search engines without having to change the infrastructure of your localized sites in the process.

Example - mixed architecture:

<html>
<head>
<link rel="alternate" hreflang="en-US" href="http://example.com/us/page.html">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/page.html">
<link rel="alternate" hreflang="fr" href="http://fr.example.com/page.html">
<link rel="alternate" hreflang="fr-CH" href="http://fr.example.com/ch/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">
</head>
<body>
...

Supported language and region codes

The value of the hreflang attribute defines the language of alternate URLs. For language codes use the ISO 639-1 standard, for country codes use the ISO 3166-1 standard.

If your site only targets different languages, you only need ISO 639-1. If you need distinction between region and language, then you also need ISO 3166-1.

Examples:

  • en: English content, not restricted to on any specific region
  • en-US: English content, targeted at the US market
  • en-MX: English content, targeted at the Mexican market

Note: Even though it is common to write the country letters in capitals, the definition does not have to be case sensitive.

Common mistakes with the hreflang attribute

No self reference used

A common source of error is a missing self reference. A good way to avoid this error is to understand hreflang as a set of localized alternates. Keep in mind you always need to reference the full set on any URL within the set.

Example - incomplete hreflang URL set / missing self referencing hreflang on current URL http://fr.example.com/page.html:

<head>
<link rel="alternate" hreflang="en-US" href="http://example.com/us/page.html">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">
</head>

Example - complete hreflang URL set with self reference on current URL:

http://fr.example.com/page.html:

<head>
<link rel="alternate" hreflang="en-US" href="http://example.com/us/page.html">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/page.html">
<link rel="alternate" hreflang="fr-FR" href="http://fr.example.com/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">
</head>

Hreflang always pointing to home page for language and region

An unexpectedly common mistake with hreflang is that the hreflang alternate points to the homepage of the specific languages or regions on all subpages instead of correctly referencing the specific subpages for the languages or regions.

Example - wrong hreflang usage on http://example.com/subpage.html:

<link rel="alternate" hreflang="en-US" href="http://example.com/">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/">
<link rel="alternate" hreflang="x-default" href="http://example.com/">

Example - correct hreflang usage on http://example.com/subpage.html:

<link rel="alternate" hreflang="en-US" href="http://example.com/subpage.html">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/subpage.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/subpage.html">

Specifying alternate URLs that do not deliver a HTTP status code 200 can cause problems.

Linking to URLs with a 3xx Redirect will cause the crawler to crawl an additional URL and therefore waste your sites crawl budget.

Linking to URLs with a 4xx or 5xx status code will cause a dead end for the crawler and make your hreflang set inconsistent. If this happens, search engines might consider your hreflang suggestions invalid and ignore it.

We suggest you monitor your status codes on a regular basis and try to avoid unnecessary redirects and dead ends.

Conflicting multiple hreflang definitions

One of the less obvious error sources is a multiple assignment of hreflang definitions. You might have specified more than one URL for a single language or region.

Conflicts within hreflang definitions are often caused by

  • multiple conflicting definitions within one hreflang declaration
  • multiple conflicting definitions within different methods (HTML head or HTTP header or XML sitemaps)

It is a lot harder to detect multiple conflicting definitions with different methods. As a result of conflicting definitions search engines might ignore your hreflang definitions.

We suggest to use only one method to implement hreflang to avoid conflicting definitions.

Conflicting hreflang and rel=canonical

If you use rel=canonical along with hreflang make sure you only use self referencing canonical URLs.

In some cases webmasters set the rel=canonical on their localized URLs to the same URL as the x-default. In other cases webmasters set the rel=canonical to the URL they would use as the x-default but they don't have a x-default at all.

This is wrong, because rel=canonical defines a preferred version of the content. Hreflang on the other hand defines alternates by language and region. These are conflicting definitions and might lead to unexpected search engine behaviour.

Read our article about rel=canonical for more information.

Example - valid usage of rel=canonical and hreflang on http://example.com/us/page.html:

<html>
<head>
<link rel="alternate" hreflang="en-US" href="http://example.com/us/page.html">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">
<link rel="canonical" href="http://example.com/us/page.html">
</head>
<body>
...

Example - proper head for http://example.co.uk/page.html:

<html>
<head>
<link rel="alternate" hreflang="en-US" href="http://example.com/us/page.html">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">
<link rel="canonical" href="http://example.co.uk/page.html">
</head>
<body>
...

Example - proper head for http://example.com/page.html:

<html>
<head>
<link rel="alternate" hreflang="en-US" href="http://example.com/us/page.html">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">
<link rel="canonical" href="http://example.com/page.html">
</head>
<body>
...

Use self referencing canonical along with hreflang on any localized version of your site.

Analyze hreflang problems in minutes with Audisto

Our software systematically audits all hreflang groups, not just single pages, by computing the full crawl data to analyze and find errors in your implementation.

Book a Demo

Incorrect usage of x-default

The x-default attribution is used to determine the default URL for all users outside your specified target regions and languages.

Possible issues with x-default:

  • wrong syntax
  • double x-default annotation
  • conflicting double x-default annotations

Whenever you use x-default, make sure you only have one x-default definition.

X-Default myth: You cannot use one URL for localized and x-default alternate

Another common misbelief is that you can specify a URL as x-default or as an alternate for a specific language or country, but you can't have the same URL specified for both. This is wrong! The x-default can and should be used in addition to the specific language or country setting.

<link rel="alternate" hreflang="en-US" href="http://example.com/page.html">
<link rel="alternate" hreflang="en-GB" href="http://example.co.uk/page.html">
<link rel="alternate" hreflang="x-default" href="http://example.com/page.html">

This is a valid example and will produce the following results:

  • US Serps, English language: http://example.com/page.html
  • British Serps, English language: http://example.co.uk/page.html
  • All other Serps in all other languages: http://example.com/page.html

Not using absolute URLs

In order to avoid problems, you better use absolute URLs for your hreflang definitions. It is not against the specification of the link tag to use relative or short URLs - so it is basically allowed. Problem with relative URLs is that search engines are more likely to interpret them wrong.

Example - relative hreflang target usage:

<link rel="alternate" hreflang="en-US" href="subpage.html">
<link rel="alternate" hreflang="en-US" href="example.com/subpage.html">

Example - absolute hreflang target usage:

<link rel="alternate" hreflang="en-US" href="http://example.com/subpage.html">

Use absolute URLs in your hreflang definitions.

Not using the right country and language codes

If you are not sure if your language and country declaration for hreflang is valid, check at ISO 3166-1 and ISO 639-1 for a list of available country and language codes.

If you have invalid country and language codes Google will show up an "unknown language codes" error in Google Search Console.

Invalid syntax in country and language code annotations

Make sure you don't have syntax errors in your hreflang definitions. Follow the standard.

Example - wrong underscore instead of hyphen:

<link rel="alternate" hreflang="en_US">

Example - correct hyphen:

<link rel="alternate" hreflang="en-US">

Example - wrongly mixing up order of language and country:

<link rel="alternate" hreflang="us-EN">

Example - correct order of language and country:

<link rel="alternate" hreflang="en-US">

Make sure you don't mix up language and country in your hreflang definitions.

Using cacheable redirects for geotargeting

In many geotargeting implementations we find 301 redirects. Working with these redirects to implement geotargeting is rather error prone due to the cacheability of 301 redirects. 301 redirects might be cached by browsers and proxies. This can lead to unexpected behaviour after changing geolocation redirect targets.

When using redirects for geotargeting, it is suggested to use non cacheable 303 redirects.

"The 303 (See Other) status code indicates that the server is redirecting the user agent to a different resource, as indicated by a URI in the Location header field, which is intended to provide an indirect response to the original request." (RFC 7231)

Incomplete hreflang URL set - no return tags

If you fail to keep your hreflang URL sets synchronized, your hreflang definitions might be considered invalid.

Example:

  • http://example.com - hreflang definitions link to fr.example.com, es.example.com and ca.example.com.
  • http://ca.example.com - hreflang definitions link to es.example.com and ca.example.com.

In this case there is a link from ca.example.com to fr.example.com, possibly leading search engines to ignore your hreflang definitions for http://fr.example.com entirely.

Google Search Console offers help to identify such errors in the International Targeting Tab. The specific error message in the Google Search console is "no return tags".

Analyze hreflang problems in minutes with Audisto

Our software systematically audits all hreflang groups, not just single pages, by computing the full crawl data to analyze and find errors in your implementation.

Book a Demo

Conflicting hreflang and Google Search Console definitions

Another popular way to cause confusion specifically for Google is having hreflang definitions conflicting with the targeting information that is defined in the Google Search Console International Targeting Tab.

If you change your localization strategy and hreflang, make sure you update your Google Search Console definitions as well.

This also applies to other search engines offering international targeting options.

How we help - Hreflang Checker

The Audisto Crawler can check your hreflang implementation for inconsistencies. During the crawl we extract all the hreflang references and mark issues with hreflang related hints. The hreflang help page describes the feature in detail. If you need personal assistance analyzing your website, just contact us. We will be happy to help.

Authors

Tobias SchwarzTobias SchwarzCTO and Founder
Christian MüllerChristian Müller