hreflang Is Probably Broken on Your Site — Here's a Zero-Dependency CLI to Prove It

Description and use

The hreflang-audit CLI detects hreflang errors in multilingual sites, enabling quick fixes for mismatches, dead links, and invalid locale codes.

Problem

Many multi-language sites have broken hreflang annotations, causing search engines to serve incorrect country versions and split rankings without obvious alerts.

Outcome

The CLI provides a concise report of hreflang clusters with failures, allowing teams to address return-tag mismatches, dead URLs, and invalid locale codes efficiently.

Workflow

• Install Node 20+. Run hreflang-audit <domain-or-sitemap>. Review the generated report for clusters and failure types. Fix the identified hreflang issues. Re-run the audit to confirm resolution. Integrate the CLI into CI to fail builds on new hreflang errors.

Evidence

After hitting the same three failure modes in audit after audit, I built hreflang-audit, an open-source, zero-dependency Node CLI.

Source

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.

Source