The hreflang guide for international websites

What does hreflang do?

If a page exists in several languages or for several countries, hreflang lets Google show the right version in every search. Google sometimes finds language versions on its own, but recommends declaring them explicitly. Google detects the language of a page with its own methods. Neither hreflang nor the HTML attribute lang is used for that.

Google does not treat translated pages as duplicates. Versions in the same language for different countries are a different matter, for example for Germany and Austria with almost identical text. Google may treat those as duplicates. hreflang then makes sure the Austrian URL still appears in Austria.

Do I need hreflang?

As soon as a page exists in several languages or in versions for different countries, hreflang is worth it. Google names three cases. The main content is fully translated. Only the navigation and footer are translated, while the main content stays in one language. Or there are versions in the same language with small regional differences. In practice, these set-ups come up most often.

There are no separate codes for regions. A version for Europe therefore gets one value for each country it is meant to reach. If your website has only one language and targets one country, you do not need hreflang.

Your URL structure does not have to match the hreflang value. Versions may sit on different domains, and Google does not use language subdomains such as fr.example.com to work out who a page is for. Which version is meant for whom is stated in the hreflang.

Language and country codes

The value consists of a language code according to ISO 639-1 and, optionally, a region code according to ISO 3166-1 Alpha-2, joined by a hyphen. Upper and lower case do not matter. Writing the region in capitals is common.

Use the plain language code as long as the content does not differ by country. Country codes are worth it when prices, shipping, legal details or wording differ. A URL can also carry several values, for example one version for Germany and Austria at the same time. The article Multiple hreflang values on one URL explains how.

x-default

x-default names the page for users whose language matches none of your versions. Google recommends it above all for language selector pages and homepages that redirect based on language or location. If you have no such page, you can name an existing version as the fallback, usually the English one.

Plan before you implement

A table of all versions saves a lot of mistakes later. For each version, note the address, language and target countries.

Each combination of language and country appears only once. Then you decide which URLs are linked. An hreflang set should only contain pages that exist in several versions, return status 200, are indexable and canonicalize to themselves. A separate Search Console property for each version is worth it. That way you see indexing and search queries for each market separately.

Which domain strategy fits?

hreflang works with any structure. The structure itself is a signal too, though. Google describes the usual options with these pros and cons.

• Country-code domain (ccTLD), such as example.de. It shows users and search engines clearly which country the website is meant for. In return it targets only one country, costs more and needs more infrastructure.
• Subdomain on a generic domain, such as de.example.com. It is quick to set up and allows servers in different locations. Users often cannot tell the target country from the name alone.
• Subdirectory on a generic domain, such as example.com/de/. It is quick to set up and needs little maintenance, because everything sits on one host. Running the versions separately is harder.

Google does not recommend URL parameters such as ?loc=de. For hreflang, the country-code domain matters most. A version on example.co.uk is aimed at the UK. An hreflang value for Ireland on the same URL contradicts that signal. The case study From ccTLDs to one gTLD shows what moving from several country domains to one domain can achieve.

Three ways to implement it

Google treats all three methods the same. Pick one. Using several at once brings no advantage and is harder to maintain.

HTML in the head

All versions carry the same block, each with full URLs.

HTTP header

For files, the server sets a Link header that is the same for all versions.

XML sitemap

In the sitemap, every <url> entry names all versions, including itself. You need the xhtml namespace for that. You can find more about sitemaps in the XML sitemap guide.

hreflang and canonical

Every language version points to itself with its canonical. A page with a canonical pointing to another URL gets no hreflang, and hreflang only points to canonical URLs. A canonical from one country version to another tells Google that only the target should be indexed. That contradicts the hreflang. Google also recommends that a page's canonical is in the same language. Examples with variants and country versions are in the article hreflang and canonical and in the canonical tag guide.

Special cases

hreflang via JavaScript and Google Tag Manager

Our own test from 2017 suggests that Google evaluates hreflang in the rendered HTML. hreflang annotations that Google Tag Manager had removed from the DOM no longer had any effect afterwards. The test ran on one website. The guide hreflang with Google Tag Manager describes how to add hreflang via GTM when your CMS cannot. You can find the test under JavaScript SEO experiment on hreflang. It is safer to deliver hreflang directly in the source code.

Checking hreflang

1. Look at a single URL in the source code and in the rendered HTML. Is the same block on all versions? The free Hreflang Checker fetches every linked language version of a page for this.
2. Open every target URL. It must return status 200, be indexable and canonicalize to itself.
3. Check the return links. Each version names all the others and itself.
4. Check the codes against ISO 639-1 and ISO 3166-1.
5. Compare the page language with the hreflang value. Google detects the language from the visible content. If a page with hreflang="fr" shows German text, the annotation is wrong. Google also advises using one language per page, for both content and navigation.
6. Compare the country-code domain with the country code. A URL on example.at with the value de-DE sends two signals that contradict each other.
7. Check the language switcher. The versions should link to each other with normal HTML links so that users can switch themselves. Google recommends this explicitly.
8. Compare the translations. Linked pages show the same content in their language. If only the template is translated and the main content is not, Google says this can create a poor user experience.
9. For the whole website, use a crawl that brings all hreflang sets together. With thousands of URLs, there is hardly any other way to find gaps.
10. In Search Console, track for each property which version ranks in which country.

Common mistakes

• The return link is missing. Google then ignores the annotation between the two pages.
• The page does not name itself.
• hreflang points to redirects, 404 pages or pages with noindex.
• Target URLs with a canonical pointing to another page.
• Relative URLs or a missing protocol.
• Wrong codes such as en-UK, or a country code without a language.
• The same combination of language and country for two URLs.
• The annotations sit outside the head, for example because a script writes them into the body.
• Users are redirected to a version automatically based on browser language or IP address. Google advises against this.

Frequently asked questions