Hreflang Checker

Validate the hreflang annotations on any page. The checker reads every annotation, then fetches the alternates and confirms each one links back, which is the check that matters: Google discards a one-way annotation entirely.

Why hreflang fails quietly

Hreflang has no failure state a person can see. A broken set does not throw an error or show a warning on the page; it simply stops influencing which version Google shows, and visitors in one country keep landing on the wrong language. The site looks correctly internationalized to everyone who checks it by eye.

Three failures account for most of it. A missing return link, where one side of a pair was updated and the other was not. An invalid code, usually a country code that is not one, which Google discards without complaint. And a missing self-reference, which is easy to skip because it feels redundant to declare a page as an alternate of itself.

All three are checkable, and all three are invisible until you check. Run this against one page per language rather than every page: the annotations are usually generated by the same template, so a fault on one page is a fault across the set.

Reading the results

The findings above the table cover the annotations themselves: a code Google cannot read, a code declared twice with two different URLs, a URL that is not absolute, and a page that leaves itself out of its own set. Each one is a fault in the markup on the page you entered, so each one is fixed in the template that generates it.

The table then reports what the other side of every pair says. Confirmed means the alternate lists this page in return and the pair holds. Missing means its HTML declares nothing pointing back, which is the fault that quietly disables the annotation, and it is fixed on the alternate rather than here. A site that sends its annotations in the HTTP Link header or its sitemap also reads as missing here, since this tool reads the HTML of every page it fetches. Unknown means the alternate could not be fetched, usually because it blocks automated requests or timed out, so its return link is still an open question. Not checked means the row falls past the 25 URLs the checker fetches, or that its href is not an address that can be fetched.

Fix the errors first, since an annotation Google discards is an annotation no return link can rescue. Then work through the missing return links one pair at a time, adding the annotation to the page that fails to reciprocate, and re-run the checker from that page to confirm the set holds from both directions.

Frequently Asked Questions

What is a return link and why does it matter?

If page A declares page B as its French alternate, page B must declare page A in return. Google treats the annotation as a claim that needs confirming from both sides, and discards a one-way claim entirely. This is the single most common reason a hreflang set that looks complete does nothing, and it is what this tool checks by fetching each alternate.

What language codes are valid?

A two-letter ISO 639-1 language code, optionally followed by a script and an ISO 3166-1 Alpha-2 country code, such as en, en-GB, pt-BR, or zh-Hant-TW. The country part is a region, never a language. The classic error is en-UK: the United Kingdom's country code is GB, so that annotation is invalid and is ignored.

The other codes that read as valid without being valid are groupings. There is no country code for Europe or for Latin America, so en-EU and es-419 are discarded, and es-LA targets Laos rather than the region its author had in mind. Where you serve a group of countries, declare each one.

How many alternates does the checker fetch?

The first 25 alternate URLs on the page. Two annotations that name the same URL share one fetch, so a set that pairs x-default with a language version spends one of the 25 rather than two. Anything past that is listed in the table with its return link marked as unchecked, so you always see the whole set and you always know which rows carry an answer.

Annotations are generated by a template, so a fault on one page is a fault across the set. Run the checker on one page per language rather than on every page.

Do I need x-default?

It is not required, but it is worth having. The x-default annotation names the page to show a searcher whose language and region match none of your alternates. Without it, Google picks one, and the page it picks is often the one you would not have chosen.

Should every page include itself?

Yes. Every page in a hreflang set must list every page in the set, including itself. A set of four language versions therefore carries four annotations on each of the four pages. Omitting the self-reference is a common mistake and breaks the set.

Can hreflang live somewhere other than the HTML?

Yes, it may be sent in the HTTP Link header or declared in the XML sitemap, and all three methods are equally valid. This tool reads the HTML only, so a page that returns no annotations here may still be annotated by one of the other methods. Use the HTTP header checker to see whether they are being sent as headers.