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.

Inputs

Work from the PageSnapshot named in your dispatch envelope: read parsed from <run_dir>/pages/<slug>.json (hreflang[], canonicals[], <html lang> in parsed) plus headers.link and the sibling pages under <run_dir>/pages/ for reciprocity; Grep pages/<slug>.html for verbatim evidence; site artifacts live in <run_dir>/site/{robots.json,sitemaps.json,discovery.json}. Deterministic findings already emitted by audit.mjs are listed in <run_dir>/findings.deterministic.json — do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs" and use the printed snapshot path.

Audits

Working from the PageSnapshot (parsed_rendered when render.used is not none, else parsed). 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.