An hreflang checker for the terminal and CI

What it checks

• invalid-code and suspicious-code: en_US with an underscore, en-uk (the United Kingdom is gb), english, or uk on its own, which is Ukrainian.
• missing-self-reference and missing-x-default: every page in a cluster must list itself, and without x-default unmatched visitors get whichever version Google picks.
• missing-return-tag: page mode fetches up to 20 distinct alternates, four at a time, and reports each one whose own tags do not point back. One-way tags are dropped by Google.
• alternate-unreachable and alternate-redirects: an alternate that errors cannot be indexed, and a redirecting one may not carry the return tag.
• noindex and canonical-conflict: hreflang on a noindexed page, or on a page whose canonical points elsewhere, is disregarded however correct the tags are.
• Sitemap mode: relative hrefs, duplicate codes, entries whose alternates are not themselves listed, and a sitemap index followed into its first five children.

Limits worth knowing

• Page mode stops fetching alternates at the --max-alternates cap and says so with an alternates-truncated warning; raise the cap for a large cluster.
• Sitemap mode confirms return tags only for alternates that are themselves url entries in the same sitemap; anything else is a not-in-sitemap warning to check in page mode.
• It checks one page's cluster or one sitemap per run, not a whole site.

Frequently asked questions

How is this different from the browser hreflang checker?

Same checks, different place. The browser version at /tools/hreflang-checker is for one URL or one sitemap you have in front of you. The CLI takes the same input in a script, prints machine-readable JSON, and returns an exit code, so a deploy can fail when a localised page loses its return tags.

Where does it read hreflang from?

From the three places Google accepts it: link rel="alternate" hreflang tags in the HTML head, the HTTP Link response header, and xhtml:link annotations inside an XML sitemap. Each reported tag is labelled with its source, so a tag declared twice in two places is visible as such.

Why does it fetch the other pages?

Because hreflang is only honoured when both pages reference each other. Reading one page tells you what it claims; fetching each alternate tells you whether the claim is reciprocated. In sitemap mode no fetch is needed, since a sitemap has to declare the whole cluster on every entry and the entries can be checked against one another.

The tags are all correct and Google still ignores them. Why?

The two usual causes are a noindex on the page, which means it is never served from search, and a canonical pointing at a different URL, since Google reads hreflang from the canonical page only. This tool reports both as errors. If neither applies, check that every alternate is itself indexable.

Can it check a whole site's hreflang?

It checks one page's cluster or one sitemap per run. To audit every localised page on a site, including alternates that point at non-indexable pages, crawl it with Crawl Cove, which builds the whole cluster as it goes and tracks it over time.