Tags for Localized Versions of Your Site

If you have multiple versions of a page for different languages or regions, tell Google about these different variations. Doing so will help Google Search point users to the most appropriate version of your page by language or region.

Note that even without taking action, Google might still find alternate language versions of your page, but it is usually best for you to explicitly indicate your language- or region-specific pages.

Some example scenarios where indicating alternate pages is recommended:

  • If you keep the main content in a single language and translate only the template, such as the navigation and footer. Pages that feature user-generated content, like forums, typically do this.
  • If your content has small regional variations with similar content, in a single language. For example, you might have English-language content targeted to the US, GB, and Ireland.
  • If your site content is fully translated into multiple languages. For example, you have both German and English versions of each page.

Localized versions of a page are only considered duplicates if the main content of the page remains untranslated.

Methods for indicating your alternate pages

There are three ways to indicate multiple language/locale versions of a page to Google:

Guidelines for all methods

  • Each language version must list itself as well as all other language versions.
  • Alternate URLs must be fully-qualified, including the transport method (http/https), so:
    https://example.com/foo, not //example.com/foo or /foo
  • Alternate URLs do not need to be in the same domain.
  • If you have several alternate URLs targeted at users with the same language but in different locales, it’s a good idea also to provide a catchall URL for geographically unspecified users of that language. For example, you may have specific URLs for English speakers in Ireland (en-ie), Canada (en-ca), and Australia (en-au), but should also provide a generic English (en) page for searchers in, say, the US, UK, and all other English-speaking locations. It can be one of the specific pages, if you choose.
  • If two pages don’t both point to each other, the tags will be ignored. This is so that someone on another site can’t arbitrarily create a tag naming itself as an alternative version of one of your pages.
  • If it becomes difficult to maintain a complete set of bidirectional links for every language, you can omit some languages on some pages; Google will still process the ones that point to each other. However, it is important to link newly expanded language pages bidirectionally to the originating/dominant language(s). For example, if your site was originally created in French with URLs on .fr, it’s more important to bidirectionally link newer Mexican (.mx) and Spanish (.es) pages to your strong .fr presence, rather than to bidirectionally link your new Spanish language variant pages (.mx and .es) to each other.
  • Consider adding a fallback page for unmatched languages, especially on language/country selectors or auto-redirecting homepages. Use the the x-default value:
    <link rel="alternate" href="http://example.com/" hreflang="x-default" />

HTML tags

Add <link rel="alternate" hreflang="https://developers.google.com/search/docs/advanced/crawling/lang_code"... > elements to your page header to tell Google all of the language and region variants of a page. This is useful if you don’t have a sitemap or the ability to specify HTTP response headers for your site.

For each variation of the page, include a set of <link> elements in the <head> element, one link for each page variant including itself. The set of links is identical for every version of the page. See the additional guidelines.

Here is the syntax of each link element:

<link rel="alternate" hreflang="https://developers.google.com/search/docs/advanced/crawling/lang_code" href="https://developers.google.com/search/docs/advanced/crawling/url_of_page" />
Syntax
lang_code A supported language/region code targeted by this version of the page, or x-default to match any language not explicitly listed by an hreflang tag on the page.
url_of_page The fully-qualified URL for the version of this page for the specified language/region.

Example

Example Widgets, Inc has a website that serves users in the USA, Great Britain, and Germany. The following URLs contain substantially the same content, but with regional variations:

URLs with regional variations
http://en.example.com/page.html Generic English language homepage that contains information about fees for shipping internationally from the USA.
http://en-gb.example.com/page.html UK homepage that displays prices in pounds sterling.
http://en-us.example.com/page.html US homepage that displays prices in US dollars.
http://de.example.com/page.html German language homepage.
http://www.example.com/ Default page that doesn’t target any language or locale; it has selectors to let users pick their language and region.

Note that the language-specific subdomains in these URLs (en, en-gb, en-us, de) are not used by Google to determine the target audience for the page; you must explicitly map the target audience.

Here is the HTML that would be in the <head> section of all the pages listed above. It would direct US, UK, generic English speakers, and German speakers to localized pages, and all others to a generic homepage. Google Search returns the appropriate result for the user, according to their browser settings.

<head>
 <title>Widgets, Inc</title>
  <link rel="alternate" hreflang="en-gb"
       href="http://en-gb.example.com/page.html" />
  <link rel="alternate" hreflang="en-us"
       href="http://en-us.example.com/page.html" />
  <link rel="alternate" hreflang="en"
       href="http://en.example.com/page.html" />
  <link rel="alternate" hreflang="de"
       href="http://de.example.com/page.html" />
 <link rel="alternate" hreflang="x-default"
       href="http://www.example.com/" />
</head>

HTTP Headers

You can return an HTTP header with your page’s GET response to tell Google about all of the language and region variants of a page. This is useful for non-HTML files (like PDFs).

Here is the format of the header:

Link: <url1>; rel="alternate"; hreflang="lang_code_1", <url2>; rel="alternate"; hreflang="lang_code_2", ...
Syntax
<url_x> The fully-qualified URL of the alternate page corresponding to the locale string assigned
to the associated hreflang attribute. The URL must include surrounding < and
> marks. Example: <https://www.google.com>
lang_code_x A supported language/region code targeted by this version of
the page, or x-default to matches any language not explicitly listed by an
hreflang tag on the page.

You must specify a set of <url>, rel="alternate", and hreflang values for every version of the page including the requested version, separated by a comma as shown in the example below. The Link: header returned for every version of a page is identical. See the additional guidelines.

Example

Here is an example Link: header returned by a site that has three versions of a PDF file: one for English speakers, one for German speakers from Switzerland, and one for all other German speakers:

Link: <http://example.com/file.pdf>; rel="alternate"; hreflang="en",
      <http://de-ch.example.com/file.pdf>; rel="alternate"; hreflang="de-ch",
      <http://de.example.com/file.pdf>; rel="alternate"; hreflang="de"

Sitemap

You can use a sitemap to tell Google all of the language and region variants for each URL. To do so, add a <loc> element specifying a single URL, with child <xhtml:link> entries listing every language/locale variant of the page including itself. Therefore if you have 3 versions of a page, your sitemap will have 3 entries, each with 3 identical child entries.

Sitemap rules:

Example

Here is an English language page targeted at English speakers worldwide, with equivalent versions of this page targeted at German speakers worldwide and German speakers located in Switzerland. Here are all the URLs present on your site:

  • www.example.com/english/page.html targeted at English speakers.
  • www.example.com/deutsch/page.html targeted at German speakers.
  • www.example.com/schweiz-deutsch/page.html targeted at German speakers in Switzerland.

Here is the sitemap for those three pages:

<?xml version="1.0" encoding="UTF-8"?>
<urlset 
  xmlns_xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>http://www.example.com/english/page.html</loc>
    <xhtml:link
               rel="alternate"
               hreflang="de"
               href="http://www.example.com/deutsch/page.html"/>
    <xhtml:link
               rel="alternate"
               hreflang="de-ch"
               href="http://www.example.com/schweiz-deutsch/page.html"/>
    <xhtml:link
               rel="alternate"
               hreflang="en"
               href="http://www.example.com/english/page.html"/>
  </url>
  <url>
    <loc>http://www.example.com/deutsch/page.html</loc>
    <xhtml:link
               rel="alternate"
               hreflang="de"
               href="http://www.example.com/deutsch/page.html"/>
    <xhtml:link
               rel="alternate"
               hreflang="de-ch"
               href="http://www.example.com/schweiz-deutsch/page.html"/>
    <xhtml:link
               rel="alternate"
               hreflang="en"
               href="http://www.example.com/english/page.html"/>
  </url>
  <url>
    <loc>http://www.example.com/schweiz-deutsch/page.html</loc>
    <xhtml:link
               rel="alternate"
               hreflang="de"
               href="http://www.example.com/deutsch/page.html"/>
    <xhtml:link
               rel="alternate"
               hreflang="de-ch"
               href="http://www.example.com/schweiz-deutsch/page.html"/>
    <xhtml:link
               rel="alternate"
               hreflang="en"
               href="http://www.example.com/english/page.html"/>
  </url>
</urlset>

Supported language/region codes

The value of the hreflang attribute identifies the language (in ISO 639-1 format) and optionally a region (in ISO 3166-1 Alpha 2 format) of an alternate URL. If there’s only one code specified, Google assumes the code to be a language code. The language doesn’t need to be related to the region. For example:

  • de: German language content, independent of region
  • en-GB: English language content, for GB users
  • de-ES: German language content, for users in Spain

For language script variations, the proper script is derived from the country. For example, when using zh-TW for users in Taiwan, the language script is automatically derived (in this example: Chinese-Traditional). You can also specify the script itself explicitly using ISO 15924, like this:

  • zh-Hant: Chinese (Traditional)
  • zh-Hans: Chinese (Simplified)

Alternatively, you can also specify a combination of script and region—for example, use zh-Hans-TW to specify Chinese (Simplified) for Taiwanese users.

Use the x-default tag for unmatched languages

The reserved hreflang="x-default" value is used when no other language/region
matches the user’s browser setting. This value is optional, but recommended, as a way for you
to control the page when no languages match. A good use is to target your site’s homepage
where there is a clickable map that enables the user to select their country.

There’s no need to specify a language code for the x-default value; the page is
targeted to users whose language settings are unmatched on your site, thus the language of the
page is irrelevant.

Troubleshooting

Common Mistakes

Here are the most common mistakes with hreflang usage:

  • Missing return links: If page X links to page Y, page Y must link back to page X. If this is not the case for all pages that use hreflang annotations, those annotations may be ignored or not interpreted correctly.
  • Incorrect language codes: Make sure that all language codes you use identify the language (in ISO 639-1 format) and optionally the region (in ISO 3166-1 Alpha 2 format) of an alternate URL. Specifying the region alone is not valid.

Debugging hreflang errors

You can use the International Targeting report to debug the most common problems. Make sure that Google has had time to crawl your pages, then visit the Language tab on the report to see if any errors were detected.

There are also many third-party tools available. Here are a few popular tools. These tools are not maintained or checked by Google.

Related Articles

Leave a Reply

Check Also
Close
Back to top button