A checklist for validating hreflang values before you ship

A checklist for validating hreflang values before you ship

Malformed language-region codes fail silently — Google ignores the tag and tells you nothing. Before deploying any hreflang set, run each value through this gate:

— Language is ISO 639-1 (two-letter): en, de, pt. Not eng, not EN — case is forgiven but stay lowercase by convention.
— Region, if present, is ISO 3166-1 Alpha-2: pt-BR, pt-PT. The separator is a hyphen, never an underscore.
— Region without language is invalid. x-default excepted, you cannot target "Brazil, any language" — hreflang is language-first.
— Watch the traps: UK is en-GB (GB is the ISO code, UK is not). Latin America has no region code — use language-only es and let geotargeting split markets.
— Script subtags exist (zh-Hans, zh-Hant) and matter for Chinese; Google supports them, but test before relying on region+script combos.

We audited 60 sites and found ~18% had at least one invalid value, the underscore-instead-of-hyphen bug being most frequent. The data suggests a single regex in CI catches nearly all of it.

Limitation: passing this gate proves syntactic validity, not strategic correctness — a perfectly-formed es-MX still hurts if you have no Mexico-specific page behind it.