seo-international

seo-international (M20)

hreflang は、どの言語・地域向け URL を検索エンジンに表示するかを伝えます。このモジュールは条件付きで実行されます。seo-vertical-detect が多言語サイト（複数の lang／ロケール URL、言語切り替え機能、または既存の hreflang）と判定した場合にのみ動作します。単一言語のサイトでは、すべての指摘が重大度 0 の not_applicable になります。スキーマタイプに関する懸念事項は references/schema-tier1.md に委ね、このモジュールではリンクレベルのローカライズのみを扱います。

入力

ディスパッチ用エンベロープで指定された PageSnapshot を使用します。<run_dir>/pages/<slug>.json から parsed（hreflang[]、canonicals[]、parsed 内の <html lang>）を読み取り、さらに headers.link と <run_dir>/pages/ 内の同階層のページから相互関係を確認します。逐語的な証拠を得るには pages/<slug>.html を Grep します。サイトのアーティファクトは <run_dir>/site/{robots.json,sitemaps.json,discovery.json} にあります。audit.mjs がすでに出力した決定論的な指摘は <run_dir>/findings.deterministic.json に記載されています。これらの ID を再出力せず、モデルが判定した指摘のみ追加してください。スナップショットがなく、URL／パスを指定して直接実行する場合は、まず node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs" を実行し、表示されたスナップショットパスを使用してください。

監査

PageSnapshot を使用して作業します（render.used が none でなければ parsed_rendered、そうでなければ parsed）。<head> 内の <link rel="alternate" hreflang="..."> から hreflang を読み取ります（HTTP Link: ヘッダーやサイトマップの xhtml:link がある場合は、それらも受け付けます）。

1. 相互参照 — ページ A が代替ページ B を宣言している場合、B も A を宣言する必要があります。一方向の hreflang は Google に無視されます。
2. BCP-47 の妥当性 — 各 hreflang 値は、有効な言語（en）または言語・地域（en-GB、pt-BR）のタグである必要があります。地域コードには ISO-3166-1 alpha-2 を使用し、言語から国を推測してはいけません（en-UK は無効です。en-GB を使用してください）。
3. 自己参照 — ページ自身を hreflang セットに含めます。
4. x-default — 言語選択ページ／フォールバック URL を示す hreflang="x-default" を少なくとも 1 つ含めます。
5. hreflang と canonical の競合 — hreflang URL は自己参照 canonical である必要があります。rel=canonical が別のページを指す URL を hreflang が指定すると、クラスターが無効になります（M2/seo-indexability と照合してください）。
6. <html lang> の一致 — ドキュメントの lang 属性は、その URL が独自の hreflang エントリーで対象としているロケールと一致する必要があります。

修正

• AUTO（fixable: auto）：ロケール→URL マップが判明している場合（ユーザーから提供された場合、サイトマップにある場合、または代替ページから検出された場合）、すべてのロケールと単一の x-default を含む完全な相互参照 hreflang リンクセットを、fix 用の <head> 差分として生成します。追加的かつ決定論的です。
• PROPOSED（fixable: proposed）：検出された代替ページから推測した部分的なセットです。書き込みの前に、ユーザーがロケールマップを確認する必要があります。
• ADVISORY（fixable: advisory）：「多言語サイトのように見えますが、ロケールマップがありません」という通知です。ツールによる書き込みは行いません。
• ロケール、地域コード、代替 URL を捏造しないでください。マップが不完全な場合は、明確に示した TODO(locale) プレースホルダーを残し、ユーザーに確認してください。

検証

• オフライン：node "${CLAUDE_PLUGIN_ROOT}/scripts/hreflang-check.mjs" --snapshot <pages/<slug>.json>（または --url <u>／--file <path>）を実行します。<link> タグとHTTP Link ヘッダー（entries、header_entries）から代替セットを解析し、BCP-47 タグを検証して（invalid_bcp47）、has_x_default、self_referenced、duplicate_langs および canonical と hreflang の競合を報告します。このモードでは相互参照を検証しません。相互参照の検証には、宣言された各代替ページを取得する --url <u> --deep [--budget 25] [--ua <preset>] が必要です。
• 相互参照の検証には、宣言された各代替ページを取得する必要があります。これらの URL（またはサイトマップ階層）を利用できない場合、ステータスは needs_api となり、誤って pass と判定されることはありません。

Findings

Findings は schema/finding.schema.json に準拠し、軸は search です。単一言語サイトでは、すべての ID が重大度 0 の not_applicable です。重大度ポリシー：5 は、サイト／テンプレートのスコープで適格性を損なう壊滅的な事実にのみ使用します。4 は重大、3 は中程度、2 は軽微、1 は表面的、0 は情報提供です。また、アクティブなカテゴリにおける established の重大度 5 の fail のみがスコアの上限を設定できます（references/scoring-model.md）。

• M20.hreflang.missing_reciprocal — ページが hreflang="de-DE" を宣言している URL から、元のページへの参照がありません。Google は一方向のアノテーションを無視するため、クラスターが形成されません（fail、重大度 4、fixable: proposed、信頼度 established）。evidence.observed には、一方向の <link> が引用されています。
• M20.hreflang.invalid_bcp47 — 例：hreflang="en-UK"（fail、重大度 3、fixable: auto、信頼度 established。en-GB を推奨）。無効な値が 1 つあると、そのエントリは無効になりますが、セット全体が無効になるわけではありません。
• M20.hreflang.missing_self — ページが自身の代替ページセットに含まれていません（fail、重大度 3、fixable: auto、信頼度 established）。
• M20.hreflang.canonical_conflict — hreflang URL の rel=canonical が別のページを指しており、クラスターが無効化されています（fail、重大度 4、fixable: proposed、信頼度 established。M2 と相互確認してください）。
• M20.hreflang.missing_xdefault — クラスターに x-default フォールバックがありません（warn、重大度 2、fixable: auto、信頼度 directional。x-default は推奨されますが必須ではなく、存在しない場合はクラスターが壊れるのではなく、セレクターのルーティングが劣化します）。
• M20.lang.mismatch — <html lang> が、この URL の hreflang エントリで示されるロケールと一致しません（warn、重大度 2、fixable: auto、信頼度 directional）。
• M20.hreflang.not_applicable — 単一言語サイト（not_applicable、重大度 0）。 プラットフォーム条件付き ID。 このモジュールは、profile.json にプラットフォーム（shopify）が記載されている場合にのみ発火する ID も 1 つ出力します。この ID は references/routing.md の § Platform-conditional finding ids に索引され、references/platforms/<id>.md の §10 で仕様が定められています。

各 finding では、verification.reproduce が上記の hreflang チェックコマンドを実行します。expected_impact は範囲と信頼度タグ付きで示されます（単独の % は使用しません）。

正確性

• hreflang は ターゲティング／クラスタリング のシグナルであり、ランキングを押し上げるものではありません。ロケールに応じて既存の URL のどれを表示するかを選択するもので、ランキングを上げるものではありません。ランキング向上の手段として売り込まないでください。
• hreflang は、質の低いコンテンツや機械翻訳されたコンテンツを 改善するものではなく、rel=canonical の代替でもありません。この 2 つは連携して機能します。
• Bing と Yandex での利用は限定的、またはまったくありません。文書で示されている恩恵の対象は Google です。検索エンジン間で同等に機能すると主張しないでください。
• 相互参照の有無は、1 ページだけからは断定できません。クロール予算内に代替ページを取得できていない場合、finding は needs_api です。一方からだけ見た状態は、一方向リンクの証拠にはなりません。