If your site serves multiple languages, hreflang is where SEO quietly breaks: page A links B, B never links back; someone writes instead of ; an alternate points at a redirect; the target canonicalizes somewhere else.
None of it is visible in the browser — all of it costs you in the SERPs. hreflang-audit is a single-file Node.js 20+ CLI with zero npm dependencies.
It crawls your site (or parses your XML sitemap, sitemap-index included), reads elements, HTTP headers, and sitemap entries, and runs 11 checks — from invalid ISO codes (with hints like → ) to missing return links and canonical conflicts.
Every finding comes with a fix hint.
Output is a human-readable report, or for machines, with exit codes designed for CI.
There's also a composite GitHub Action so you can run it on a weekly schedule and fail the build when hreflang regresses.
Try it in under a minute (no npm install) What it checks Code Check E001 invalid ISO language/script/region codes E002 underscore locales () E003 relative hreflang URLs E004 missing return links E005 conflicting entries (same lang, two URLs) E006 broken target URLs W101–W105 missing self-reference / x-default, redirected targets, canonical mismatches, duplicates Honest limitations HTML is parsed with tolerant regexes rather than a full DOM, JavaScript-rendered pages are not executed, and it complements — not replaces — Search Console's reports.
Repo: github.com/madahzadeh/hreflang-audit — MIT licensed.
Feedback and issues welcome; sitemap/HTML mismatch detection is next on my list.