Products → Hreflang & International SEO Skill Pack for Claude Code
Hreflang & International SEO Skill Pack for Claude Code
A Claude Code skill pack that audits hreflang as a graph, not a per-page checklist — catching the failure that breaks most multi-language sites silently: reciprocity, self-reference, x-default coverage, code validity, duplicate codes, and 404 targets. Plus a pass/fail guard for CI. Runs in your editor, no dependencies, no SaaS, €49 once.
v1.0.0 — live. The checker was run against a real live hreflang implementation at real scale: apple.com's 137-locale cluster, 0 Blocking findings across every checked pair. The worked outputs ship in the download (esempio/).
The problem this solves
Hreflang tags get added once, by whoever built the locale switcher, and then
nobody checks them again. Page A declares an alternate pointing at page B — but B
was built later, or by someone else, and never got the tag pointing back at A.
Google's own documentation is explicit: not reciprocal, the whole pair gets
ignored. Nobody sees an error. The wrong locale just keeps showing up in search
results. A locale page that doesn't reference itself in its own hreflang set gets
its entire cluster discarded. A typo (en_US instead of
en-US) silently invalidates one annotation. A URL restructure leaves
a hreflang tag pointing at a page that now 404s. You could open every locale page
and trace every alternate by hand. Nobody does it after the first launch — and it
only gets worse as locales get added.
What's inside
| Skill | What it does |
|---|---|
hreflang-audit | Cross-references hreflang as a graph across your whole crawled site: reciprocity (A → B but no B → A), self-referencing, x-default coverage, language/region code validity, duplicate codes pointing at different URLs, hreflang targets that 404, canonical-vs-hreflang conflicts. Optional live verification for targets the crawl didn't already cover. |
hreflang-guard | The same checks as a binary pass/fail guard: --assert exits non-zero on a regression. Catches a locale page that silently lost its self-reference, or a reciprocal pair that broke, before it reaches production. |
Plus two dependency-free helper scripts: hreflang-check.mjs (the code validator + cross-page reciprocity engine) and crawl.mjs (the raw-HTML crawler shared with the other mulino.tools packs — it already extracts every hreflang tag per page), an install guide, and worked examples against a real live site.
What it is not
- It does not rewrite your hreflang tags for you. It finds the broken pair and names the fix; editing the template is yours.
- It is not a guess machine. Every finding traces to a value it actually parsed or fetched — reciprocity is computed from the real crawled/verified graph, never assumed.
- It is not a SaaS. No account, no API key, no monthly fee, no npm dependencies. Files in a folder.
Why €49
If your time is worth €50 an hour, the pack pays for itself the first time it catches one broken reciprocal pair — the kind of bug that quietly serves the wrong language to an entire market for months before anyone traces it back to a missing tag. Then it keeps checking on every deploy, which nobody was going to do manually across dozens of locale pairs.
What you get
- 2 skills and 2 dependency-free helper scripts
- Install guide (~2 minutes) and a QA checklist showing how each skill was tested
- Worked examples: a real 137-locale hreflang implementation (apple.com), a real negative control (a single-locale site), and a labelled synthetic fixture exercising every check branch (invalid code, duplicate code, missing self-reference, missing reciprocity, 404 target, canonical conflict)
- 12 months of updates — a bounded, honest commitment, not "lifetime"
- 30-day refund, no questions asked, through Gumroad
Requirements
- Claude Code (free)
- Node.js 18+. No npm dependencies, no API keys, no account.
- The site's locale pages reachable over HTTP(S), or a crawl.json you already have.
FAQ
- Isn't this what hreflang testing tools/browser extensions already show?
- Most tools check one page at a time — do its tags look syntactically valid. This checks the whole graph: does the other end of every declared pair actually point back. That's the failure mode that's the most common cause of hreflang being ignored.
- Does it need every locale page in the crawl to work?
- No. Structural checks (code validity, self-reference, duplicates, x-default)
work on whatever's crawled. Reciprocity checking needs the target page too —
either already in the crawl, or fetched live with
--verify. Anything not checked is reported as "not verified," never silently assumed fine. - What counts as a valid hreflang code?
- The format Google documents: ISO 639-1/639-2 language, optional script,
optional ISO 3166-1 region — e.g.
en,en-US,pt-BR— or the reserved valuex-default. - Do I need to know how to code?
- No. You need Claude Code and Node.js. You describe the site in plain English and the skills run the script and read the output.
- Will you keep it updated?
- Updates for 12 months from purchase, through your Gumroad library and logged in a changelog. After that the version you have keeps working; further updates are not included. Deliberately not a "lifetime" promise.
AI disclosure
The skills are written instructions for an AI coding assistant and were authored with AI assistance. The helper scripts are conventional code and report only measured/fetched values — no invented metrics, ratings, or stats anywhere in the product or on this page.
Fifth in the mulino.tools technical-SEO set for Claude Code: the Technical SEO Skill Pack audits and fixes an existing site, the Site Migration & Redirects Skill Pack covers the replatform/relaunch moment, the Rendering & JavaScript SEO Skill Pack covers the raw-vs-rendered gap JS frameworks introduce, the Robots, Sitemap & Crawl-Directives Skill Pack covers robots.txt vs sitemap.xml, and this one covers hreflang reciprocity across your whole locale graph, plus a CI guard for it.