S SCHEMA.BIZ

Last updated:

Hreflang Checker

This hreflang checker reads a page's or sitemap's hreflang tags, checks every language and region code, and tests the return links.

Our server fetches the page as SchemaBizBot, then its HTML is checked here in your browser.

The example has mistakes to find.
Check a page by its URL, paste its HTML or check a sitemap to see its hreflang annotations here.

How to use the hreflang checker

"Check a URL" sends the address to our server, which fetches the page as SchemaBizBot; the HTML comes back and is checked in your browser, with a summary of the fetch (status, redirects, size, time) and a "Copy a link to this check" button. "Paste HTML" checks markup in your browser only. "Sitemap" takes a sitemap's address, which our server fetches, or its pasted XML. A link such as /seo/hreflang-checker/?url=https://example.com/ runs the check when it opens.

"Try an example page" loads a pour-over coffee guide whose set lists de and en-UK but not the page itself: an error for the missing self-reference, a warning that Google reads en-UK as plain en, and a note for the missing x-default. "Try an example sitemap" loads two entries; the German one lists only itself, so it doesn't link back to the English page.

What the Hreflang tab shows

It gathers the annotations from the HTML head and any Link header and checks each code, each address and the set as a whole, labeling every finding Error, Warning, Note or OK. The other tabs cover the rest of the head; the meta tag checker opens on the overview.

Reading the return-link matrix

After a URL check, the checker fetches up to 10 alternates, 4 at a time, and draws a matrix: one row per page, one column per version. ✓ means that page lists the version at the expected address, ≠ means it lists the code at another address, and ✗ means it doesn't list it. The "Links back" column says whether each page points to the one you checked. In the example sitemap, the German row shows ✗ under en and x-default.

An alternate that doesn't link back, fails to load, is noindex or names another page as canonical is an error; one that redirects is a warning. So is one that links back but leaves a version out of its own set (✗ in its row): Google says each language version must list itself as well as all the others. An alternate our server couldn't fetch just then, because of too many checks in a short time, shows as a "couldn't be checked just now" note; check again a minute later. For a sitemap, the checker compares its entries with one another and draws one matrix per group of linked pages, for the first 20 groups.

That fetch is what makes it an hreflang tester and not only an hreflang validator: every code can be valid and the set still ignored if the pages it names don't link back. Pasted HTML can't be checked for return links: nothing in it is fetched, so the alternates are never loaded. Every other check still runs.

How Google uses hreflang

Hreflang tells Google which pages are versions of the same content for different languages or regions, so it can send searchers to the one meant for them. It doesn't tell Google what language a page is in: Google says it uses neither hreflang nor the lang attribute to detect language.

It works in pairs. Google's documentation says that if two pages don't both point to each other, the tags are ignored, though it still processes the pairs that do. The set can go in the HTML head, a Link HTTP header or the sitemap; the three methods are equivalent.

Hreflang codes: language, script, region and x-default

  • Language (required): ISO 639-1, two letters, such as en or pt.
  • Script (optional): ISO 15924, as in zh-Hant or zh-Hans-US.
  • Region (optional): ISO 3166-1 alpha-2, after the language, as in en-GB or fr-CA.
  • x-default: the fallback page for searchers no other code fits.

Codes are case-insensitive. Valid: en, de-AT, zh-Hant-TW, x-default. Invalid: be meant as Belgium (it's Belarusian; a region never stands alone), en-UK (UK is reserved, so Google ignores it), es-419 (outside the supported standards), en_US (an underscore).

The 8 most common hreflang mistakes

Google names the first, third and fourth as common mistakes; the rest break other rules in its documentation.

  1. Missing return links. A lists B, but B doesn't list A. Error, with ✗ in the matrix.
  2. No self-reference. Every version must list itself too. Error. An alternate that links back but leaves out a version, itself included, is a warning.
  3. Incorrect language codes. Three-letter codes such as fil, underscores and unknown codes are errors.
  4. Incorrect region codes. A country alone, numeric regions such as 419 and unknown codes are errors; EU, UN or UK is a warning that Google reads only the language.
  5. Addresses that aren't fully qualified. Google needs https://example.com/foo, not //example.com/foo or /foo. Error.
  6. One code for two URLs. de pointing to two pages leaves no single German version. Error.
  7. Links outside the head. Google reads hreflang only in a well-formed <head>, so these are errors. A link that also carries media is a warning.
  8. Alternates that aren't the real page. Redirecting is a warning; noindex or a canonical naming another page is an error. The checked page's own canonical pointing elsewhere is a warning.

Two smaller findings are notes: no x-default, and regional versions without a language-only one.

Examples

A two-language site

An English guide and its German translation. Both pages carry the same two links:

<link rel="alternate" hreflang="en" href="https://example.com/en/brewing-guide/">
<link rel="alternate" hreflang="de" href="https://example.com/de/bruehanleitung/">

The checker passes the set, with one note for the missing x-default.

A site with regions

UK and US pages, a general English page, a German site on its own domain and a country selector as the fallback. Google calls a generic en page beside regional ones a good idea; it may also be one of them. All five pages carry this set:

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

In a sitemap, the same set needs the XHTML namespace on <urlset> and one <url> per address, each listing every version:

<?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>https://example.com/uk/</loc>
    <xhtml:link rel="alternate" hreflang="en-GB" href="https://example.com/uk/"/>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/us/"/>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.de/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/"/>
  </url>
  <url>
    <loc>https://example.com/us/</loc>
    <!-- the same five xhtml:link elements -->
  </url>
  <!-- one <url> each for /en/, example.de and the selector page, with the same five links -->
</urlset>

Paste it under "Sitemap" and the checker reads each <loc> and its links, checks codes and self-references, and draws the matrices. An alternate without its own <url> entry is left to its page's HTML. A sitemap index is recognized, and you're told to check the sitemaps it lists.

Hreflang and canonical tags

For pages with hreflang, Google's advice is to specify a canonical in the same language, or the best substitute language. A German page whose canonical points to the English page sends two contradicting signals, which is why the checker flags canonicals that point elsewhere, on the page and on its alternates. Google also ignores, for canonicalization, a canonical link carrying an hreflang attribute, so keep them in separate elements. The canonical checker covers the canonical tag itself.

Frequently asked questions

FAQ

What does x-default do?

It names the page to show when none of your language or region versions fits the searcher. Google recommends it for that fallback and designed it for language selector pages. It goes in the same set as the other codes, on every version. Without it the checker adds a note, not an error.

Do hreflang URLs have to be on the same domain?

No. Alternates can be on other domains, so example.de can be the German version of a page on example.com. The usual rules still apply: fully qualified addresses, and every version listing all the others, itself included.

Hreflang in HTML, HTTP headers or the sitemap: which is better?

Google treats the three as equivalent and sees no benefit in using more than one. Choose the one your site can keep correct; a sitemap keeps the whole set in one file. When a page has both HTML links and a Link header, the checker reads both and warns if they list different sets.

Does the checker store my pages or sitemaps?

Nothing you paste leaves your browser. For a URL check, the address goes to our server, which fetches the page (and, for return links, up to 10 alternates) or the sitemap as SchemaBizBot. Like every tool on the site, the checker records what kind of check ran, such as the tab, hreflang counts and the codes of the problems found, never a tag's text or the page's content. A URL check also records the checked page's address without its query string. See the privacy policy.