Hreflang checker that quotes the rule behind every error

01Check an hreflang set

Three shapes go in the box and the tool works out which one you pasted. The served HTML of a page holding <link rel="alternate" hreflang="..."> elements, a sitemap fragment holding <xhtml:link> children under each url element, or plain lines of a code followed by a URL. A Link: response header line is read too. Give the URL of the page being checked so the self reference can be matched. To check return links offline, paste more than one page and start each block with a line holding a hash and that page's URL.

Paste mode runs entirely in your browser and makes no request of any kind. The one thing a browser cannot do is read another site's page, so the Fetch button and the return link button call a small relay the author of this site runs on workers.dev. It fetches exactly the URL you give over https, GET only, follows at most five redirects, keeps at most 1 MB of the body, gives up after 12 seconds, refuses private address space, and stores nothing. Every relay error is printed here word for word.

Reference data in this page is the two letter language subtags, the two letter region subtags and the four letter script subtags read from the IANA Language Subtag Registry file dated 2026-08-08, the registry W3C names as the one place every subtag is found. Counted from those embedded lists when this page loaded, that is language subtags, region subtags and script subtags, deprecated entries excluded and listed separately.

02Every rule the checker applies, and the line it comes from

Each row is one check in the box above. The right hand column is the sentence the rule is taken from, quoted, with a link to the page it sits on. Where Google and the specification say different things, the checker reports Google's rule as the error and the specification as the reason.

03What hreflang looks like on big homepages

The numbers below come from this site's own tag census, one direct HTTPS GET of the homepage of each of the 83 hosts in the 2026-08-24 robots census on this site, redirects followed, captured 2026-09-06, with 58 hosts returning HTTP 200 with served HTML and therefore measured. Every figure is read from the published file by code and none of it is typed into this page. An hreflang entry is counted as a link element with rel alternate and an hreflang attribute, and a code counts as invalid when it does not match language, optional script, optional region, or x-default.

Set sizes are lopsided. Among the 23 measured homepages that carry any hreflang, the median set holds 16 entries, the largest single set on one homepage holds 157 entries, and the census holds 918 entries across every measured homepage, all captured 2026-09-06 by one HTTPS GET per host. So the two mistakes worth checking first are the ones that scale with the set. A missing self reference costs one entry on every page in the set, and a missing return link costs the pairing on both ends.

The raw machine readable file behind every figure here is published beside this page at data/homepage-tag-census-2026-09-06.json, with its capture date, its instrument, its method and its limits inside the file.

04Common questions

Whether x-default is required

No. Google describes a fallback page for languages that match no version as something to consider adding, and calls the reserved x-default value recommended for specifying that fallback, which is a recommendation and not a syntax rule. So the checker reports a missing x-default as a recommendation miss rather than an error. Google also says there is no need to specify a language code for the x-default value, because that page is targeted to users whose language settings match nothing on the site, so the language of the page is irrelevant. In the census, 9 of the 23 measured homepages that carry hreflang have no x-default entry, captured 2026-09-06 by one HTTPS GET per host.

hreflang and canonical together

They do different jobs and Google keeps them apart. A rel canonical annotation that carries an hreflang, lang, media or type attribute is ignored for canonicalization, so an alternate link is not read as a canonical suggestion. Google also states that for canonicalization purposes it prefers URLs that are part of hreflang clusters, which is a second reason to get the reciprocal set right. Point each language version's canonical at itself, and let the hreflang set do the language targeting.

Header, link element or sitemap

Google documents three carriers for the same annotation. One link element for each page variant including the page itself, placed in the head element of every variation. HTTP response headers, which Google notes are useful for non HTML files such as PDFs. Or a sitemap, where the xhtml namespace is declared on the urlset element as xmlns:xhtml="http://www.w3.org/1999/xhtml" and each url element lists every alternate version of the page, including itself. The self reference rule is the same in all three. The checker reads all three shapes because the mistake usually survives the move from one carrier to another.

Why return links matter

Google lists missing return links first among the common hreflang mistakes, where page X links to page Y but page Y does not link back to page X, and states plainly that if two pages don't both point to each other the tags will be ignored. A one way annotation is not a weak signal, it is a discarded one. Paste every page in the set into the box above and the checker prints the exact pairs that fail, in the direction they fail. Or press the return link button after a check and the relay fetches each alternate, up to 25 of them, and reports whether it points back.

What this page sends anywhere

In paste mode, nothing. The code lists, the rules and the matching all live in this page, and the text you paste never leaves the browser tab. Fetch mode and the return link button send the URLs you asked for to the relay named above, and nothing else, and only when you press the button. That matters more than it used to, because the Search Console International Targeting report, which is where hreflang errors used to be reported, has been deprecated, while Google says it will continue to support and use hreflang tags on your pages. The reporting went away and the rules did not, so the check has to happen on your side now. Worth knowing as well, Google states that it does not use hreflang or the HTML lang attribute to detect the language of a page and uses algorithms instead. hreflang tells Google which version to show a given user, not what language a page is in.

06Where these numbers come from

By Michael Lip, who fetched and published the census on this page and wrote the checker above.

Every census figure on this page is recomputed by code from the dataset file published beside the page, with the capture date and the instrument stated in the same sentence as the figure. A value that could not be fetched is held as null and rendered as unknown, never defaulted to something flattering. The code lists in the tool are parsed straight out of the IANA Language Subtag Registry file dated 2026-08-08, and the counts printed under the tool are counted from those embedded lists in your browser when the page loads, not typed by hand.

I run four small utility sites through Search Console and publish their impression and click counts on this site rather than a forecast. I read crawler traffic in raw server logs, where a request claiming to be Googlebot has to be checked against Google's published IP range files, because the user agent string is free to forge. The host list behind the census above is the one I fetched robots.txt from on 2026-08-24 and re-tested days later, which is where the observation that a handful of hosts give Googlebot a different answer from the star group came from. Same list, same method, new tag.

• SPECGoogle, tell Google about localized versions of your page, for the self reference, the fully qualified URL, the return link, x-default, the supported code standards and the reserved codes.
• SPECRFC 5646, BCP 47, for the hyphen, the subtag order, the UK exclusion and the case conventions.
• DATAIANA Language Subtag Registry, file dated 2026-08-08, for the embedded code lists, the deprecated subtags and the suppressed scripts.
• SPECW3C, choosing a language tag and ISO 15924 code list, for the one code per language rule, the shortest tag rule and the script list.
• DATAThe census file, every figure in section 03, captured 2026-09-06 and published unmodified.