A pre-deploy QA gate for any hreflang change

A pre-deploy QA gate for any hreflang change

Hreflang regressions ship silently because nothing 500s — the page renders fine, the signal just rots. We bake a gate into CI so changes can't merge blind:

— Syntax check: every value matches the ISO language(-region) pattern; separator is a hyphen. Fail the build on the first malformed code.
— Self-reference check: every URL includes itself in its own hreflang set. Missing self-tags are the quietest, deadliest error.
— Reachability check: HEAD every declared alternate; any non-200 (404, redirect chain, soft-404) fails. Alternates pointing at redirects are a frequent and invisible cause of ignored annotations.
— Reciprocity check: build the directed graph of annotations and assert it's symmetric. Asymmetry = future "no return tags" in GSC, caught before deploy instead of weeks after.
— Canonical consistency: assert each page's canonical equals its self-hreflang target.

We instrumented this for one client and pre-deploy catches dropped their GSC International Targeting errors by ~70% quarter over quarter. The data suggests most hreflang debt is preventable at merge time, not discovered in production.

Caveats: a static crawl misses client-rendered annotations — run the gate against rendered HTML if you inject tags via JS. And the gate proves *consistency*, not *strategy*; it cannot tell you whether es-419 was the right target, only that it's well-formed and reciprocated.