seo-international (M20)

hreflang tells search engines which language/region URL to serve. This module is conditional: it only runs when seo-vertical-detect flags a multilingual site (multiple lang/locale URLs, language switcher, or existing hreflang). On monolingual sites every finding is not_applicable at severity 0. Schema-type concerns defer to references/schema-tier1.md; this module owns link-level localization only.

Audits

Working from the PageSnapshot (rendered_dom if present, else raw_html). Read hreflang from <link rel="alternate" hreflang="..."> in <head> (also accept HTTP Link: headers / sitemap xhtml:link when present):

Reciprocity — if page A declares an alternate B, B must declare A back. One-way hreflang is ignored by Google.
BCP-47 validity — each hreflang value is a valid language (en) or language-region (en-GB, pt-BR) tag; region is ISO-3166-1 alpha-2, not a country-of-language guess (en-UK is invalid; use en-GB).
Self-reference — the page lists itself in its own hreflang set.
x-default — at least one hreflang="x-default" for the language-selector / fallback URL.
hreflang↔canonical conflict — an hreflang URL must be self-canonical; pointing hreflang at a URL whose rel=canonical is a different page neutralizes the cluster (cross-check M2/seo-indexability).
<html lang> agreement — the document lang attribute matches the locale this URL targets in its own hreflang entry.

Fixes

AUTO (fixable: auto): when the locale→URL map is known (supplied by the user, a sitemap, or discovered alternates), generate a complete reciprocal hreflang link set — every locale + a single x-default — as a <head> diff for fix. Additive and deterministic.
PROPOSED (fixable: proposed): a partial set inferred from discovered alternates that needs the user to confirm the locale map before write.
ADVISORY (fixable: advisory): "this looks multilingual but no locale map exists" — never written by the tool.
Never fabricate locales, region codes, or alternate URLs. If the map is incomplete, leave a clearly-marked TODO(locale) placeholder and ask the user.