Check the hreflang tags of a page

How to use the tool

Paste the address of a page, then click “Check”. The tool reads the page and lists every hreflang declaration found in the HTML and in the HTTP Link header. If you also enter a sitemap, it looks for the page’s entry in that file and adds its declarations. Each row of the table gives the code, the URL, the source and the exact tag found, so you can locate it in the page’s code.

The tool then reads the declared alternate pages, ten at most, after the starting page. Beyond that, it says so and leaves the rest aside. One analysis counts as a single request: the tools on this site accept twenty requests every ten minutes per visitor, all tools combined.

Each problem found links to the rule behind it: Google’s documentation on localized versions, its documentation on canonical URLs, or the ISO standards for language and country codes.

What the tool checks

• Codes. Google accepts a language in ISO 639-1 format, optionally followed by a region in ISO 3166-1 Alpha 2 format, plus the x-default value.¹ A country code on its own, an underscore instead of a hyphen or a region outside the standard are flagged.
• Absolute URLs. Alternate URLs must be fully qualified, with http or https; a form such as /page or //example.com/page does not work.¹
• Self-reference. Each version must list itself, as well as all the others.¹
• Duplicate languages. The same code used for two different URLs. Annotations describe one page per language or region: two URLs under the same code contradict each other.
• Return links. If two pages don’t both point to each other, Google ignores their annotations.¹ The tool looks, in each alternate page, for the link back to the starting page, and shows the tag found.
• HTTP status of alternates. A declared URL must answer 200. Google ignores the content of a redirecting URL and does not keep a page returning a 4xx error in its index.³
• Canonicals. An alternate page whose canonical points to another version, or a starting page canonicalized elsewhere, contradicts the annotations.²

Three ways to declare the versions of a page

Google reads hreflang annotations in three places and treats them as equivalent.¹ The most common is the link tag, placed in the head of each version:

<link rel="alternate" hreflang="en" href="https://www.example.com/page/">
<link rel="alternate" hreflang="fr" href="https://www.example.com/fr/page/">
<link rel="alternate" hreflang="x-default" href="https://www.example.com/page/">

For a file that is not an HTML page, a PDF for instance, the same information goes in the HTTP Link header, sent by the server with the response:

Link: <https://www.example.com/guide.pdf>; rel="alternate"; hreflang="en",
      <https://www.example.com/fr/guide.pdf>; rel="alternate"; hreflang="fr"

Finally, the sitemap can carry the annotations: under each url element, one xhtml:link element per version, the page itself included, with the xhtml namespace declared at the top of the file.¹ This method lightens the code of pages on a large site, but it is harder to check, which is why the tool accepts a sitemap URL as an option. The guide on what Google says about XML sitemaps covers the rest of that file.

Google notes that using all three methods at once brings nothing.¹ Pick one and keep it up to date. When the same URL is declared under the same code by two sources, the tool does not count it as a duplicate.

Language and region codes

An hreflang code starts with a two-letter language from ISO 639-1⁴: en, fr, de. It can continue with a two-letter region from ISO 3166-1 Alpha 2⁵: fr-BE for French in Belgium, en-GB for English in the United Kingdom. Google also accepts a script in ISO 15924 format, such as zh-Hant for Traditional Chinese. Case does not matter.¹

Google lists these traps among common mistakes: a country code used alone, or a reserved region code such as EU, UN or UK, which has no effect.¹ Some two-letter codes exist in both lists with two meanings: be is the Belarusian language; Belgium is BE only in the region position, as in fr-BE. The tool cannot guess the intent in that case, so check that the code really names the language of the page.

The x-default value names the page to show when no other language or region matches the visitor. It suits a language or country selector, or the main version of the site.¹ It is optional, and the tool does not flag its absence.

Return links, the most often forgotten rule

An hreflang annotation only counts if both sides confirm it. If the English page lists the French page, the French page must list the English page in return; otherwise, Google ignores the tags.¹ The typical case: a new language version added on one page only, or a template updated in a single language.

The return link must target the exact URL of the starting page. A difference in protocol, www or trailing slash is enough to miss it: the tool flags this case separately, as a near-miss return link, with the URL found. It also checks that the return link uses the same code the starting page declares for itself, and that each alternate lists itself.

For a new market, Google notes that linking the new version to the original language matters more than linking all the variants to one another.¹ Connecting the new page to the old one, in both directions, comes first.

hreflang and the canonical tag

Both signals must point the same way. When you use hreflang, Google asks you to specify a canonical page in the same language, or the best possible substitute language if none exists.² An English version whose canonical points to the French version asks Google to keep the French one in its place, which contradicts the annotation. The tool flags it and names the version targeted.

Same logic for the starting page: if its canonical names another URL, Google will normally keep that other URL, and the annotations belong on it and should point to it. Google also says that, for localization, it prefers URLs that are part of an hreflang cluster²: clean annotations help the right canonical get picked.

Two versions that differ only by region, en-GB and en-US for example, are not duplicates when their main content is adapted. Google only treats localized versions as duplicates if the main content remains untranslated.¹

What the tool cannot see

The tool reads the HTML as the server sends it. Tags added by JavaScript after loading are not there. It does not check where the tags sit either: Google asks for them in a well-formed head and suggests an HTML validator when in doubt.¹

For a sitemap index, the tool does not open each file: enter the sitemap that lists the page. It does not follow the redirects of alternate pages, since an alternate that redirects is precisely what needs fixing. To look at one alternate page in more detail, the meta tags and Open Graph generator reads its canonical and main tags.

Finally, Google does not use hreflang to recognize the language of a page: its algorithms handle that.¹ Annotations serve to show the right version to the right visitor, among pages already indexed.

Frequently asked questions