If your site serves multiple languages, hreflang is where SEO quietly breaks: page A links B, B never links back; someone writes en_US instead of en-US; 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 <link rel="alternate" hreflang> elements, HTTP Link: headers, and xhtml:link sitemap entries, and runs 11 checks — from invalid ISO codes (with hints like en-UK → en-GB) to missing return links and canonical conflicts.
Every finding comes with a fix hint. Output is a human-readable report, or --json 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)
git clone https://github.com/madahzadeh/hreflang-audit.git
cd hreflang-audit
npm run demo # offline demo with seeded issues
node hreflang-audit.mjs https://example.com/ # audit a real site
What it checks
| Code | Check |
|---|---|
| E001 | invalid ISO language/script/region codes |
| E002 | underscore locales (en_US) |
| 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.
This article was originally published by DEV Community and written by Dr. Reza Madahzadeh.
Read original article on DEV Community