seo-hreflang

出力例：examples/seo-hreflang-airbnb-com-20260514/HREFLANG-REPORT.md

Hreflang 監査

AgriciDaniel/claude-seo の seo-hreflang スキル（MIT）を応用しています。コンセプトと検証ルールは同スキルに由来し、この実装は当社のバックエンド（SE Ranking MCP + Firecrawl + WebFetch + seo-google 経由の Google APIs）に合わせて再構築されています。

多言語または複数地域向けサイトの hreflang 実装を検証します。SE Ranking の監査レベルの hreflang の問題を明らかにし、サンプルページを解析して実際に出力される <link rel="alternate" hreflang="…"> タグを確認し、サイトマップと照合して、客観的な指標に基づく上位の修正項目テーブルとともに、3 つの判定（PASS、NEEDS-FIX、BROKEN）のいずれかを提示します。

前提条件

• SE Ranking MCP サーバーが接続されていること。
• Claude の WebFetch ツールが利用可能であること（Firecrawl が利用できない場合のフォールバック）。
• ユーザーが対象ドメイン（例：example.com）を指定すること。任意で、インベントリ作成対象の代表的なページの明示的なリスト、および /sitemap.xml 以外にある場合はサイトマップの URL を指定できます。
• 前提となるスキル（推奨）： このドメインで seo-technical-audit または seo-sitemap がすでに実行されていること。既存の監査がない場合、このスキルが監査を作成します（クレジット消費量が大幅に増加します）。

プロセス

1. 対象を検証し、事前チェックを行います。 正式な 3 段階の事前チェック（クレジット残高、Firecrawl の利用可否、Google APIs）については、skills/seo-firecrawl/references/preflight.md を参照してください。このスキル固有の補足事項：

   • 続行する前に、ドメインを正規化します（プロトコルと末尾のスラッシュを削除します）。
   • このスキルの SE Ranking の推定コスト：既存の監査を再利用する場合は約 5～10 SE Ranking クレジット（URL ごとのインベントリには最大約 3 Firecrawl クレジット）。
   • Firecrawl：任意です。利用できない場合は WebFetch にフォールバックし、利用可能な場合は約 6 Firecrawl クレジットを使用します（上限あり）。利用可能な場合、ステップ 4（URL ごとの hreflang インベントリ）は、formats: ["rawHtml"] を指定してホームページと代表的な 5 ページを対象に実行されます。Firecrawl が利用できない場合、ステップ 4 は WebFetch にフォールバックします。WebFetch は Markdown のみを返し、<head> 内の <link rel="alternate"> タグを通知なく削除するため、網羅性は低下します。Firecrawl が利用可能な場合でも WebFetch を強制するには、--no-firecrawl を渡してください。
   • Google APIs：ティア 1（GSC）を利用すると、ステップ 6（hreflang で対象指定された代替 URL の GSC 検証）が有効になります。詳細な拡張機能の仕様については、skills/seo-google/references/cross-skill-integration.md を参照してください。

2. 監査を検索するか、更新します。 DATA_listAudits → DATA_getAuditStatus

   • 対象ドメインの監査を一覧表示します。最近の監査（30 日未満）があれば、それを使用します。
   • 30 日より古い場合は、DATA_recheckAudit を実行し、done になるまで待ちます。
   • 監査がない場合は、DATA_createStandardAudit で監査を作成する前にユーザーに確認します。作成にはクレジットを消費します。

3. SE Ranking の hreflang に関する検出結果を取得します。 DATA_getAuditReport + DATA_getAuditPagesByIssue

   • SE Ranking の監査は hreflang のエラーを直接検出するため、まずグラウンドトゥルースとして提示します。
   • DATA_getAuditReport から、コードまたはカテゴリーが hreflang に一致するすべての問題を抽出します（一般的なコード：hreflang_no_return_tag、hreflang_invalid_lang_code、hreflang_conflict、hreflang_missing_x_default、hreflang_canonical_mismatch、hreflang_no_self_reference）。
   • 重要な hreflang の問題（件数 ≥ 1）ごとに、DATA_getAuditPagesByIssue を呼び出し、影響を受ける URL を列挙します。
   • 01-audit-hreflang-issues.md に保存し、hreflang-issues.csv に反映します。

4. URL ごとの hreflang タグの一覧 mcp__firecrawl-mcp__firecrawl_scrape（推奨）／WebFetch（フォールバック）

   • サンプルの選定： ホームページと、DATA_getDomainPages から選んだ代表的なページを最大 5 件（トラフィックの降順で並べます。URL 構造から異なる言語パス（/en/、/fr/、/de/ など）が分かる場合は、それらのページを優先します）。
   • Firecrawl の場合（URL あたり 1 クレジット、合計約 6 クレジット）：firecrawl_scrape(url=..., formats=["rawHtml"]) を呼び出します。rawHtml を指定してください。デフォルトの html の後処理では、多くのサイトで <link rel="alternate"> が削除されるためです。<head> からすべての <link rel="alternate" hreflang="…" href="…"> を解析します。取得する情報：ソース URL、hreflang 属性、href、および自分自身を参照しているかどうか。
   • WebFetch のフォールバック（Firecrawl がない場合）：各 URL の取得を試み、Markdown のレスポンスから hreflang を抽出します。WebFetch は <head> のリンクタグを削除した Markdown を返すことが多いため、この方法では検出数が少なくなります。HREFLANG-REPORT.md に Per-URL inventory: degraded coverage — Firecrawl not installed; some hreflang tags may be missed. と記載します。
   • 検証ルールを適用します（全ルールは references/validation-rules.md を参照）：
     • 自己参照タグ： ページ自身の URL が、そのページ自身の hreflang セットに含まれている必要があります。
     • 相互参照タグ： すべての代替リンクが相互に参照し合っている必要があります。ページ A が B を fr として指定している場合、ページ B は A を en（または該当する言語）として指定する必要があります。
     • x-default： 各セットの代替のうち、少なくとも 1 つは hreflang="x-default" を使用する必要があります。
     • 言語・地域コードの検証： すべての値は有効な ISO 639-1 言語コードであり、任意で - に続けて ISO 3166-1 Alpha-2 地域コードを付けられます。検出される一般的な誤り：eng（en を使用）、jp（ja を使用）、en-uk（en-GB を使用）、es-LA（該当する ISO 地域コードはありません）。
     • 競合の検出： 同じ hreflang 値（例：de-DE）が複数の異なる URL に指定されている場合は競合です。Google は競合するセットを無視します。
     • canonical との整合性： ページに <link rel="canonical"> がある場合、ページ自身の URL（または自己参照 hreflang の URL）と一致する必要があります。正規 URL ではないページの hreflang は、Google によって無視されます。
     • プロトコルの一貫性： セット内のすべての URL で同じスキームを使用する必要があります（HTTPS を推奨）。
   • 02-per-url-hreflang.md に保存し、検出事項を hreflang-issues.csv に追記します。

5. サイトマップレベルの hreflang（適切な場合は seo-sitemap に委ねます）

   • ユーザーのドメインでサイトマップベースの hreflang（サイトマップ内の <xhtml:link rel="alternate" …>）を使用している場合、このスキルでは構造と一貫性のみを確認します。サイトマップ全体の分析（孤立ページ、ページの欠落、エントリの破損）は seo-sitemap の担当です。サイトマップと監査結果の差分確認が対象に含まれる場合は、明示的に推奨してください。
   • サイトマップを取得します。 https://{domain}/sitemap.xml を試します。404 の場合は /robots.txt を取得し、Sitemap: ディレクティブを探します。サイトマップインデックスの場合は、各子サイトマップを再帰的に取得します。
   • サイトマップ内の hreflang を検証します：
     • サイトマップで xmlns:xhtml="http://www.w3.org/1999/xhtml" 名前空間が使用されていますか？サイトマップで hreflang を指定するには必須です。
     • hreflang の代替を含む各 <url> エントリでは、そのエントリ自身が代替セットに含まれていますか（自己参照）。
     • ある <url> エントリに記載されたすべての代替は、同じ代替セットを持つ独自の <url> エントリとして相互に参照されていますか（相互参照タグ）。
     • 言語・地域コードは有効ですか（ステップ 4 と同じルールを適用します）。
   • URL ごとの一覧と照合します（ステップ 4）： サンプル URL の HTML に hreflang の代替が 4 件記載されている一方で、その URL のサイトマップエントリに 6 件記載されている場合、この不一致は競合です。Google はどちらを採用する場合もあり、一貫性の欠如によってシグナルが弱まります。
   • 03-sitemap-hreflang.md に保存し、検出事項を hreflang-issues.csv に追記します。

6. hreflang 対象の代替ページの GSC 検証（google-api.json が存在し、tier ≥ 1 の場合のみ）

   • hreflang セット内で href の対象として登場するドメイン（例：example.com、example.de、example.fr）ごとに、GSC での検証を確認します。 python3 scripts/gsc_query.py --property "{property}" --json（ステータスのみを確認します。PROPERTY_NOT_VERIFIED が返されないことを確認してください）。
   • これが重要な理由： Google は、クロスドメインの hreflang 設定に参加するすべてのドメインを検証することを明確に推奨しています。example.de が代替ページとして登録されていても、このアカウントで検証されていなければ、hreflang シグナルが弱まり、Google がどのように解釈しているかを確認できません。
   • HREFLANG-REPORT.md に「## hreflang 対象の GSC 検証」というセクションを設け、対象ドメインごとに verified／not verified／not configured のいずれかを記載します。
   • 対象ドメインのプロパティが検証されていない場合は、Medium の重大度で修正項目として記載します（「Google Search Console で {domain} を検証してください — クロスドメイン hreflang の信頼性確保に必要です」）。
   • 障害発生時の契約については、skills/seo-google/references/cross-skill-integration.md の「Trigger pattern」を参照してください。

7. 判定をまとめる

   • 判定のヒューリスティック（Tips を参照）を適用して、PASS、NEEDS-FIX、または BROKEN を出します。
   • hreflang-issues.csv を重大度の降順、次に件数の降順で並べ替えます。
   • 上位 10 件の修正項目の表と判定を含む HREFLANG-REPORT.md を作成します。

出力形式

次のフォルダーを作成します：seo-hreflang-{target-slug}-{YYYYMMDD}/

seo-hreflang-{target-slug}-{YYYYMMDD}/
├── 01-audit-hreflang-issues.md   (SE Ranking audit findings filtered to hreflang)
├── 02-per-url-hreflang.md         (per-URL <link rel="alternate"> inventory + validation findings)
├── 03-sitemap-hreflang.md         (sitemap-level hreflang validation; defer details to seo-sitemap)
├── evidence/
│   ├── homepage-rawhtml.html      (raw HTML from Firecrawl, for the homepage sample)
│   ├── sample-{n}-rawhtml.html    (raw HTML for each sampled URL)
│   └── sitemap.xml                (raw fetched sitemap)
├── hreflang-issues.csv            (load-bearing: URL, issue code, severity, fix)
└── HREFLANG-REPORT.md             (PRIMARY: verdict + top fixes table)

HREFLANG-REPORT.md の形式：

# Hreflang Audit: {domain}

> Audit date {YYYY-MM-DD} · Sample size: {n} URLs · Languages detected: {comma-separated list}

## Verdict: {PASS | NEEDS-FIX | BROKEN}

Reasoning: {1–2 sentences anchored in concrete numbers from the data}.

## Summary

| Source | Findings | Severity breakdown |
|---|---|---|
| SE Ranking audit | {n} | Critical: {n} · High: {n} · Medium: {n} · Low: {n} |
| Per-URL HTML inventory | {n} | … |
| Sitemap | {n} | … |

## Top fixes (impact-ranked)

| # | URL | Issue | Severity | Fix |
|---|---|---|---|---|
| 1 | {URL} | {issue code} | {severity} | {one-line fix} |
| 2 | … | … | … | … |
| ... up to 10 |

## Languages detected

| Language | URL count | Self-ref OK | Return tags OK | x-default OK |
|---|---|---|---|---|
| en-US | {n} | ✓ / ✗ {count} | ✓ / ✗ | ✓ / ✗ |
| de-DE | {n} | … | … | … |
| ... |

## Per-URL inventory ({n} URLs sampled)

| URL | Alternates | Self-ref | x-default | Notable issues |
|---|---|---|---|---|
| {URL} | {n} | ✓/✗ | ✓/✗ | {short text} |
| ... |

## Sitemap-level hreflang
- xhtml namespace declared: {✓/✗}
- URLs with hreflang alternates: {n}
- Self-reference within sitemap: {✓ all / ✗ {count} missing}
- Return tags within sitemap: {✓ all / ✗ {count} missing}
- Per-URL HTML vs sitemap consistency: {✓ all match / ✗ {count} mismatched}
- Full sitemap-vs-audit analysis: see `seo-sitemap` (orphans, broken entries, lastmod).

## GSC verification of hreflang targets

| Domain | Verified | Notes |
|---|---|---|
| {domain1} | ✓ / ✗ | {note if unverified} |
| ... |

(Or: `GSC verification: not configured (run bash extensions/google/install.sh)`.)

## Coverage notes

- Per-URL inventory tool: {Firecrawl rawHtml | WebFetch fallback (degraded — some hreflang tags may be missed)}.
- Pages sampled: homepage + {n} representative pages (selection: top traffic from `DATA_getDomainPages`).

## Apply

- Walk `hreflang-issues.csv` row-by-row; each row is one specific change (URL + issue + fix).
- After applying changes, re-run `seo-technical-audit` to refresh SE Ranking's findings, then re-run this skill to verify.

hreflang-issues.csv の列：url,issue_code,severity,fix,source。source は audit | html | sitemap | gsc のいずれかです。

ヒント

• SE Ranking Data API のレート制限である 10 req/sec を守ってください。
• 可能な場合は既存の監査結果を再利用してください。このスキルで新しい監査を作成する操作は、圧倒的にコストがかかります。
• 判定の目安：
  • PASS： Critical の問題が 0 件、High の問題が 2 件以下、サンプル URL のすべてに自己参照、x-default、相互参照の戻りタグがある、すべての言語・地域コードが有効、canonical が自己参照の hreflang と一致している。
  • NEEDS-FIX： High の問題が 1 件以上、または Medium の問題が 5 件を超える、または次のいずれかに該当する（x-default がない、サンプルページの 25% を超えるページで戻りタグがない、言語・地域コードに誤りがある、サイトマップと HTML の内容が一致しない）。
  • BROKEN： Critical の問題が 1 件以上、または hreflang を実装しているのにホームページに自己参照がない、または hreflang を出力しているにもかかわらずページの canonical が別のページを指している（Google はセット全体を無視します）、またはサンプル URL の 50% を超える URL に戻りタグがない。
• HREFLANG-REPORT.md のすべての主張は、hreflang-issues.csv の行を根拠としてください。関係者から判定について質問された場合は、CSV を使って説明してください。
• 1 ページあたりの言語バリエーションが 50 を超えるサイトでは、URL ごとの HTML 実装によって <head> が肥大化します。代わりにサイトマップベースの実装を推奨してください。コードは生成しないでください。この成果物は診断用であり、コード生成用ではありません。
• このスキルでは、文化的な適応、コンテンツの同等性、ロケール形式は評価しません。これらは翻訳・QA の対象であり、hreflang 自体が技術的に正しいかどうかとは別の問題です。ユーザーがこれらの評価を希望する場合は、翻訳チームを案内してください。このスキルが答えるのは「技術的な hreflang シグナルは機能しているか」であり、「ローカライズされたコンテンツの品質は良いか」ではありません。
• クロスドメイン hreflang（例：example.com ↔ example.de）では、ステップ 6 の GSC チェックが最も有用な追加確認となります。両方のドメインを確認することは、Google が明示的に推奨しています。
• 誤検知を防ぐための一般的な注意点： サンプルページに国際化が不要な理由がある場合（例：単一地域のサイト）、hreflang タグが 0 件でも問題ありません。このスキルでは、サンプルページのいずれかが hreflang を出力しているかを確認して検出します。どのページも出力していない場合、判定は PASS となり、「No hreflang implementation detected — single-language site.」という注記が付きます。
• サイトマップと監査結果の差分確認には seo-sitemap を、技術的な健全性全般の確認には seo-technical-audit を併用してください。このスキルの対象は hreflang の正確性に限られます。
• 問題ごとのルール表（重大度、検出ロジック、推奨される修正方法）の全容については、references/validation-rules.md を参照してください。