The latest articles on DEV Community by Dr. Reza Madahzadeh (@madahzadeh). https://dev.to/madahzadeh https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4095136%2Fe46efd05-165b-458e-86ee-218cc3f49937.jpg https://dev.to/madahzadeh en Dr. Reza Madahzadeh Wed, 26 Aug 2026 06:19:32 +0000 https://dev.to/madahzadeh/i-built-a-zero-dependency-cli-to-audit-hreflang-international-seo-47bm https://dev.to/madahzadeh/i-built-a-zero-dependency-cli-to-audit-hreflang-international-seo-47bm <p>If your site serves multiple languages, hreflang is where SEO quietly breaks: page A links B, B never links back; someone writes <code>en_US</code> instead of <code>en-US</code>; 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.</p> <p><strong>hreflang-audit</strong> 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 <code>&lt;link rel="alternate" hreflang&gt;</code> elements, HTTP <code>Link:</code> headers, and <code>xhtml:link</code> sitemap entries, and runs 11 checks — from invalid ISO codes (with hints like <code>en-UK</code> → <code>en-GB</code>) to missing return links and canonical conflicts.</p> <p>Every finding comes with a fix hint. Output is a human-readable report, or <code>--json</code> 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.</p> <h2> Try it in under a minute (no npm install) </h2> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code>git clone https://github.com/madahzadeh/hreflang-audit.git <span class="nb">cd </span>hreflang-audit npm run demo <span class="c"># offline demo with seeded issues</span> node hreflang-audit.mjs https://example.com/ <span class="c"># audit a real site</span> </code></pre> </div> <h2> What it checks </h2> <div class="table-wrapper-paragraph"><table> <thead> <tr> <th>Code</th> <th>Check</th> </tr> </thead> <tbody> <tr> <td>E001</td> <td>invalid ISO language/script/region codes</td> </tr> <tr> <td>E002</td> <td>underscore locales (<code>en_US</code>)</td> </tr> <tr> <td>E003</td> <td>relative hreflang URLs</td> </tr> <tr> <td>E004</td> <td>missing return links</td> </tr> <tr> <td>E005</td> <td>conflicting entries (same lang, two URLs)</td> </tr> <tr> <td>E006</td> <td>broken target URLs</td> </tr> <tr> <td>W101–W105</td> <td>missing self-reference / x-default, redirected targets, canonical mismatches, duplicates</td> </tr> </tbody> </table></div> <h2> Honest limitations </h2> <p>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.</p> <p>Repo: <a href="https://github.com/madahzadeh/hreflang-audit" rel="noopener noreferrer">github.com/madahzadeh/hreflang-audit</a> — MIT licensed. Feedback and issues welcome; sitemap/HTML mismatch detection is next on my list.</p> seo node opensource webdev