If you run a multi-language site, there's a good chance your hreflang is broken right now. Not visibly — Google doesn't send you an email. It just quietly serves the wrong country version, splits your rankings, and you find out months later in Search Console.
After hitting the same three failure modes in audit after audit, I built hreflang-audit, an open-source, zero-dependency Node CLI.
The three failures that cause most hreflang damage
1. Return-tag mismatches. Page A declares B as its French alternate, but B never points back to A. Google treats the whole cluster as invalid. This is the single most common failure I see.
2. Alternates pointing at dead URLs. hreflang that targets a redirect, a noindexed page, or a 404 is ignored — and after a migration this happens at scale without anyone noticing.
3. Invalid locale codes. en-UK instead of en-GB, latam as a region, inconsistent casing across templates. Each one silently drops a page from the cluster.
Why zero-dependency
SEO tooling shouldn't require a 200-package install chain to run in CI. hreflang-audit needs Node 20+ and nothing else — run it in a pipeline and fail the build when someone breaks international targeting.
Usage
Point it at your domain or an XML sitemap, get a report of every cluster with its failures. That's it.
It ships with a test suite and CI (v1.0.0). If you find a case it misses, open an issue — I'm actively maintaining it. And if international SEO is your problem generally, I consult on exactly this.
Top comments (0)