hreflang-check

/digital-marketing-pro:hreflang-check

目的

多言語・複数地域向け SEO の hreflang タグ実装を監査します。hreflang アノテーションは、どの言語・地域向けのページをどのユーザーに表示するかを検索エンジンに伝えます。実装が正しくない場合、検索結果に誤った言語版が表示されたり、ページ同士が同じ検索クエリで競合したり、コンテンツが適切に配信されないことで海外からのオーガニックトラフィックを失ったりします。このコマンドでは、hreflang の実装を徹底的に技術監査し、すべての言語版が正しいアノテーションで相互参照されているか、各ページが自分自身を参照しているか、参照が双方向になっているか（ページ A がページ B を指している場合、ページ B もページ A を指しているか）、言語・地域コードが有効か、x-default フォールバックが設定されているか、存在しないページを指す参照がないかを確認します。

多言語・複数地域向けウェブサイトを運営するあらゆるブランドにとって重要です。hreflang のエラーは、国際 SEO で最もよく見られる問題の一つです。ユーザーには見えず、手動の QA ではほとんど発見されず、影響を受けるすべての市場で検索パフォーマンスを静かに低下させます。双方向参照が一つ欠けているだけでも、検索エンジンが言語版を正しく関連付けられず、誤ったページが上位表示されたり、重複コンテンツのシグナルによって両方の言語版が抑制されたりする可能性があります。このコマンドは、実装エラーをすべて具体的な修正手順と修正後のコード例とともに提示します。

必要な入力

ユーザーは次の情報を提供する必要があります（または入力を求められます）。

• ウェブサイトの URL またはサイトマップの URL：監査の起点です。単一のページ URL（そのページと参照先の代替ページの hreflang を監査）、サイトマップの URL（サイトマップに記載されたすべてのページを監査）、または確認対象の特定ページ URL の一覧を指定できます。注：このプラグインはウェブサイトを直接クロールしません。URL が指定された場合は、分析用に HTML ソースまたは hreflang データを提供するよう案内されます。代わりに、HTML ソース、hreflang タグのセット、またはエクスポートした hreflang データを直接貼り付けることもできます
• 確認対象の特定ページ URL（任意）：監査対象を絞るページのサブセットです。サイト全体ではなく、特定のセクション（例：すべての商品ページ、すべてのブログ記事）を監査する場合に便利です。省略した場合、提供されたデータ内で hreflang アノテーションを持つすべてのページを監査します
• 想定される言語・地域コード（任意）：hreflang アノテーションに含めるべき言語・地域コードのセットです（例：en-US、de-DE、fr-FR、es-ES、ja-JP）。デフォルトでは、profile.json の言語設定にあるブランドの設定済み言語が使用されます。言語版の不足を検出するために使われます。たとえば、ブランドが de-DE を対象としているのにページに de-DE の hreflang がない場合、不足として報告されます

プロセス

1. ブランドコンテキストを読み込む：~/.claude-marketing/brands/_active-brand.jsonを読み込み、アクティブなスラッグを確認してから、~/.claude-marketing/brands/{slug}/profile.jsonを読み込みます。言語設定を読み込み、必要な言語（主要言語、副次言語、コンテンツ言語）を確認します。これらを、各ページが参照することが望ましい hreflang の期待値セットとして扱います。対象市場のコンプライアンスルール（skills/context-engine/compliance-rules.md）と業界コンテキストを適用します。また、~/.claude-marketing/brands/{slug}/guidelines/_manifest.jsonにガイドラインがあるか確認し、存在する場合は国際 SEO ガイドラインを読み込みます。~/.claude-marketing/sops/に代理店の SOP があるか確認します。ブランドが存在しない場合は、「まずブランドを設定しますか（/digital-marketing-pro:brand-setup）？」と尋ねるか、デフォルト設定で進めます。
2. hreflang データを取得する：URL が指定されている場合、実際のウェブサイトのクロールには外部ツールが必要であり、このプラグインは任意のウェブサイトに HTTP リクエストを送信しないことを伝えます。以下のいずれかの形式で hreflang データを提供するよう案内します：（a）<link rel="alternate" hreflang="..." href="...">タグを含むページの未加工 HTML ソース、（b）HTTP ヘッダーの hreflang アノテーション、（c）xhtml:link hreflang エントリーを含む XML サイトマップ、（d）URL ごとの hreflang アノテーションを一覧にした SEO ツール（Screaming Frog、Sitebulb、Ahrefs）からの構造化エクスポート、または（e）URL と言語の対応を手動でまとめたリスト。HTML または hreflang データがすでにインラインで提供されている場合は、そのまま解析に進みます。
3. すべての hreflang アノテーションを解析する：提供されたデータから hreflang アノテーションをすべて抽出します。各ページについて、そのページ自身の URL と、関連する href URL を含むすべての hreflang 属性のマップを作成します。実装方法によって修正方法が異なるため、各アノテーションのソース（HTML の <link> タグ、HTTP ヘッダー、XML サイトマップ）を記録します。すべてのページについて、どのページをどの言語で参照しているかを示す完全な相互参照マトリクスを作成します。
4. 各ページの hreflang が正しいか確認する：hreflang アノテーションがあるすべてのページについて、次の確認を行います。
   • (a) 自己参照タグの有無：すべてのページに、そのページ自身の言語・地域コードで自身を指す hreflang アノテーションが必要です。自己参照タグの欠落は、最も一般的な hreflang エラーであり、検索エンジンがそのページの hreflang セット全体を無視する原因になります。重要度：重大。
   • (b) 双方向参照：en-US のページ A が de-DE のページ B を参照している場合、ページ B も en-US のページ A を参照している必要があります。すべての参照ペアで双方向の整合性を確認します。一方向の参照は検索エンジンによってエラーとして扱われ、アノテーションセット全体が無視される可能性があります。重要度：重大。
   • (c) 有効な言語・地域コード：すべての hreflang 値について、言語部分は ISO 639-1、任意の地域部分は ISO 3166-1 Alpha-2 に照らして検証します。よくあるエラー：en-GBではなくen-UKを使用する、enではなくengなどの3文字コードを使用する、言語プレフィックスを付けずにUSなどの国コードだけを使用する。有効でないコードの重要度：重大（検索エンジンが無視します）。標準外だが解析可能なコードの重要度：警告。
   • (d) x-default タグの有無：特定の hreflang に一致する言語がないユーザー向けのフォールバックページを指す、x-default hreflang アノテーションがあるか確認します。通常は英語版または言語選択ページを指定します。x-default がないと、対象外の地域のユーザーに任意の言語版が表示される可能性があります。重要度：警告。
   • (e) 言語コードの重複がないこと：同じ言語・地域コードを持つ複数の hreflang アノテーションが、異なる URL を指していないか確認します。コードが重複すると曖昧さが生じ、その言語のアノテーションがすべて検索エンジンに無視される可能性があります。重要度：重大。
   • (f) URL が絶対 URL であること：hreflang アノテーションのすべての href 値が、相対パスではなく絶対 URL（https://またはhttp://で始まる）であることを確認します。仕様上、hreflang の相対 URL は無効です。重要度：重大。
   • (g) URL の一貫性：参照先 URL のプロトコル（すべて HTTPS またはすべて HTTP）、www の有無、末尾のスラッシュの規則が一貫しているか確認します。一貫性がない場合、検索エンジンが参照先を別のページとして扱う可能性があります。重要度：警告。
5. ブランドの言語設定と相互参照する：hreflang アノテーションで見つかった言語・地域コードのセットを、ブランドで設定された言語（profile.json の言語設定、またはユーザーが指定したコード）と比較します。設定済みの言語が hreflang アノテーションに含まれていない場合は、その旨を指摘します。これは、ブランドが積極的に対象としている言語に hreflang の対応がなく、検索エンジンがその言語版へユーザーを適切に誘導できないことを意味します。また、ブランド設定にない hreflang 言語コードも指摘します。これらは別の場所で設定された正当な言語である場合も、提供を終了した言語版の古いアノテーションである場合もあります。
6. コードスニペット付きの優先順位を付けた修正リストを作成する：見つかった問題ごとに、修正済みの hreflang コードを具体的に提示します。自己参照タグが欠落している場合は、追加する正確な<link rel="alternate" hreflang="xx-XX" href="https://...">タグを提示します。双方向参照に不整合がある場合は、逆方向の参照が欠けているページに追加するタグを提示します。無効なコードの場合は、有効な言語・地域値に修正したコードを提示します。x-default が欠落している場合は、適切なフォールバック URL を含む推奨 x-default タグを提示します。ページごとに修正をまとめて、ページ単位で実装できるようにし、さらに問題の種類ごとにもまとめます（例：「47 件すべてのブログ投稿で自己参照タグが欠落」）。これにより、47 件それぞれを個別に修正するのではなく、テンプレートを1か所修正してシステム全体の問題に対処できます。

出力

以下を含む、構造化された hreflang 監査レポートです。

• Hreflang 監査スコア：実装全体の品質スコア（0～100）です。正しいアノテーションの割合を全アノテーション数に対して算出し、問題の重大度に応じて重み付けします。重大な問題はスコアを大きく下げ、警告は中程度に、情報項目はわずかに下げます
• 監査の概要統計：監査したページ数、見つかった hreflang アノテーションの総数、検出された言語・地域コードの種類数、見つかった問題の総数（重大・警告・情報別の内訳）、hreflang が完全に正しく実装されているページの割合です
• 問題の種類別の内訳：各チェック項目の検出結果を分類して表示します。自己参照タグの欠落（件数と該当ページ）、参照先なし（存在しないページ、または応答しないページへの参照）、無効な言語・地域コード（無効なコードと修正案）、x-default の欠落（フォールバック設定のないページ）、双方向参照の不一致（参照が一方向のみのページペア）、言語コードの重複（同じ言語に対して競合するアノテーションがあるページ）、相対 URL（絶対パスでないアノテーション）、URL の一貫性に関する問題（プロトコル、www の有無、末尾のスラッシュの不一致）
• 具体的な修正の推奨事項：各問題について、実装にそのまま使える修正済み hreflang コードスニペットを提示します。ユーザーは、修正済みの <link> タグまたはサイトマップエントリをコピーして、ページに直接追加できます。修正内容は、ページ単位での実装向けと、サイト全体に適用する体系的な修正向けの両方に分類します
• 言語カバレッジマトリックス：ページ（行）と言語・地域コード（列）を示す表です。各セルは、正しい hreflang アノテーションが存在する（合格）、問題を含むアノテーションが存在する（警告）、またはアノテーションが欠落している（未対応）ことを示します。どのページで hreflang のカバレッジが完全か、どのページに不足があるかをすぐに把握できます
• ブランドの言語設定との比較：ブランドで設定されている言語と、hreflang アノテーションで見つかった言語を並べて比較します。ブランドが対象としているにもかかわらず hreflang でサポートされていない言語（カバレッジ不足）と、ブランドの設定にない hreflang 言語（古い設定、または管理されていない可能性がある言語）を明らかにします
• 実装方法に関する注記：アノテーションの取得元（HTML のリンクタグ、HTTP ヘッダー、XML サイトマップ）に応じた、修正の適用方法を案内します。HTML の <head> へのタグの追加方法、HTTP ヘッダーの設定方法、xhtml:link エントリを使った XML サイトマップの更新方法を説明します

使用するエージェント

• seo-specialist — hreflang の技術監査を主導します。HTML、HTTP ヘッダー、XML サイトマップから hreflang アノテーションを解析します。国際 SEO の仕様に基づいて、7 つの検証項目（自己参照、双方向参照、有効なコード、x-default、コードの重複、絶対 URL、URL の一貫性）をすべて実行します。見つかった各問題について、修正済み hreflang コードスニペットを生成します。hreflang のエラーが国際検索での可視性に与える SEO 上の影響を評価し、オーガニックトラフィックの振り分けに最も大きな効果がある修正を優先するための指針を提示します。hreflang の仕様詳細とベストプラクティスについては、skills/technical-seo/international-seo.md を参照します
• localization-specialist — 言語・地域コードを ISO 639-1 および ISO 3166-1 規格に照らして検証します。hreflang の言語カバレッジをブランドで設定された言語と照合し、カバレッジ不足を特定します。また、技術的には有効でも、ブランドの対象市場には適さない可能性がある言語コード（中国語の市場を区別してターゲティングする場合に、汎用的な zh ではなく zh-Hans または zh-Hant を使うなど）にフラグを付けます。カバレッジマトリックスに言語ごとの背景情報を追加し、ブランドの市場戦略に基づいて適切な言語・地域の粒度を推奨します