# SEO International > Audit and generate hreflang annotations for multilingual sites — check reciprocity, BCP-47 validity, self-reference, x-default, hreflang/canonical conflicts, and agreement, and emit reciprocal hreflang link sets. Module M20 (conditional). Feeds the Search SEO score. - Skill: `hainrixz/seo-international` (Agent Skill) - Install (CLI): `npx skillmds@latest add hainrixz/seo-international` - Raw SKILL.md: https://api.skillmd.com/api/skills/hainrixz/seo-international/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: Hainrixz (https://skillmd.com/u/hainrixz) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/hainrixz/seo-international --- # 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 `/pages/.json` (`hreflang[]`, `canonicals[]`, `` in `parsed`) plus `headers.link` and the sibling pages under `/pages/` for reciprocity; Grep `pages/.html` for verbatim evidence; site artifacts live in `/site/{robots.json,sitemaps.json,discovery.json}`. Deterministic findings already emitted by `audit.mjs` are listed in `/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" --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 `` in `` (also accept HTTP `Link:` headers / sitemap `xhtml:link` when present): 1. **Reciprocity** — if page A declares an alternate B, B must declare A back. One-way hreflang is ignored by Google. 2. **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`). 3. **Self-reference** — the page lists itself in its own hreflang set. 4. **x-default** — at least one `hreflang="x-default"` for the language-selector / fallback URL. 5. **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). 6. **`` 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 `` 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. ## Verification - Offline: `node "${CLAUDE_PLUGIN_ROOT}/scripts/hreflang-check.mjs" --snapshot .json>` (or `--url ` / `--file `) — parses the alternate set from the `` tags **and** the HTTP `Link` header (`entries`, `header_entries`), validates BCP-47 tags (`invalid_bcp47`), and reports `has_x_default`, `self_referenced`, `duplicate_langs` and the canonical-vs-hreflang conflict. Reciprocity is **not** in this mode: it needs `--url --deep [--budget 25] [--ua ]`, which fetches each declared alternate. - Reciprocity requires fetching each declared alternate; when those URLs (or a sitemap tier) are unavailable, status is `needs_api`, **never** a false `pass`. ## Findings Findings conform to `schema/finding.schema.json`; axis `search`. On a monolingual site every id is `not_applicable` at severity 0. **Severity policy**: 5 is reserved for catastrophic, eligibility-killing facts at site/template scope; 4 major · 3 moderate · 2 minor · 1 cosmetic · 0 informational — and only an `established` severity-5 `fail` in an active category can cap a score (`references/scoring-model.md`). - `M20.hreflang.missing_reciprocal` — the page declares `hreflang="de-DE"` for a URL that does not point back; Google ignores one-way annotations, so the cluster does not form (`fail`, severity 4, `fixable: proposed`, confidence `established`). `evidence.observed` quotes the one-way ``. - `M20.hreflang.invalid_bcp47` — e.g. `hreflang="en-UK"` (`fail`, severity **3**, `fixable: auto`, confidence `established`; recommend `en-GB`). One bad value invalidates that entry, not the whole set. - `M20.hreflang.missing_self` — the page is absent from its own alternate set (`fail`, severity 3, `fixable: auto`, confidence `established`). - `M20.hreflang.canonical_conflict` — an hreflang URL whose `rel=canonical` points at a different page, which neutralizes the cluster (`fail`, severity 4, `fixable: proposed`, confidence `established`; cross-check M2). - `M20.hreflang.missing_xdefault` — the cluster has no `x-default` fallback (`warn`, severity **2**, `fixable: auto`, confidence `directional` — `x-default` is recommended, not required, and its absence degrades selector routing rather than breaking the cluster). - `M20.lang.mismatch` — `` disagrees with the locale this URL claims in its own hreflang entry (`warn`, severity 2, `fixable: auto`, confidence `directional`). - `M20.hreflang.not_applicable` — monolingual site (`not_applicable`, severity 0). **Platform-conditional ids.** This module also emits 1 id that fires only when `profile.json` names the platform (`shopify`). It is indexed in `references/routing.md` § Platform-conditional finding ids and specified in `references/platforms/.md` §10. Each finding: `verification.reproduce` runs the hreflang-check command above; `expected_impact` is banded + confidence-tagged (no naked %). ## Honesty - hreflang is a **targeting/clustering** signal, not a ranking boost: it selects which existing URL to show in a locale, it does not raise rankings. Don't sell it as a ranking lever. - hreflang does **not** fix thin or machine-translated content, and it is not a substitute for `rel=canonical` — the two work together. - Bing and Yandex use it weakly to not at all; the documented beneficiary is Google. Don't claim cross-engine parity. - Reciprocity cannot be asserted from one page. If the alternates were not fetched within the crawl budget, the finding is `needs_api` — a one-sided view is not evidence of a one-way link.