Tell Google about localized versions of your page
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.
Methods for indicating your alternate pages
There are three ways to indicate multiple language/locale versions of a page to Google:
<link rel="alternate" hreflang="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.
Each variation of the page should 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="lang_code" href="url_of_page" />
- A supported language/region code targeted by this version of the page, or
x-defaultto match any language not explicitly listed by an hreflang tag on the page.
- The fully-qualified URL for the version of this page for the specified language/region.
<link>tags near the top of the
<head>element. At minimum, the
<link>tags must be inside a well-formed
<head>section, or before any items that might cause the
<head>to be closed prematurely, such as
<p>or a tracking pixel. If in doubt, paste code from your rendered page into an HTML validator to ensure that the links are inside the
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:
- 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; 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 should be pasted into 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>
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:
- The fully-qualified URL of the alternate page corresponding to the locale string assigned to the associated hreflang attribute. The URL must include surrounding < > marks. Example:
- A supported language/region code targeted by this version of the page, or
x-defaultto matches any language not explicitly listed by an hreflang tag on the page.
You must specify a set of
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.
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"
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.
- Specify the xhtml namespace as follows:
- Create a separate
<url>element for each URL.
<url>element must include a
<loc>child indicating the page URL.
<url>element must have a child element
<xhtml:link rel="alternate" hreflang="supported_language-code">that lists every alternate version of the page, including itself. The order of these child
<xhtml:link>elements doesn't matter, though you might want to keep them in the same order to make them easier for you to check for mistakes.
- See the additional guidelines.
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="http://www.sitemaps.org/schemas/sitemap/0.9" 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>
- 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" />
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. (The language need not 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
Do not specify a country code by itself. Google does not automatically derive the language from the country code. You can specify a language code by itself if you want to simplify your labeling. Adding the country code after the language to restrict the page to a specific region. Examples:
be: Belarusian language, independent of region (not Belgium French)
nl-be: Dutch for Belgium
fr-be: French for Belgium
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.
The reserved value
hreflang="x-default" 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.
Here are the most common mistakes with
- 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.)