hreflang チェッカー（多言語サイトの設定確認）

hreflang validator for live URLs and HTML files

多言語サイトの hreflang を URL（GET のみ）または HTML ファイルから読み取り、言語コード・自己参照・相互リンク・x-default・canonical との整合性をページごとに報告します。

Claude Hermes Agent Codex CursorMIT（改変・再配布・商用利用可）Python

できること

日本語版・英語版など、言語ごとのページをもつサイトの hreflang 設定をページ単位で確認します。

HTML の <link rel="alternate" hreflang> と HTTP の Link ヘッダーを読み取り
言語コードの妥当性（ISO 639-1 の言語、任意で文字体系・地域）。jp、en-UK、en_US のようなよくある間違いを指摘
自分自身への hreflang（自己参照）があるか、x-default があるか
相互リンク：A が B を指すなら B も A を指しているか、両者で同じセットになっているか
canonical との整合性：canonical が別 URL を指していないか、指定先がリダイレクトや 200 以外になっていないか
公開前の確認用に、ビルド済みの HTML フォルダもチェック可能

使い方

python scripts/hreflang_check.py https://example.com/ https://example.com/en/ --follow --out hreflang.json
python scripts/hreflang_check.py --files ./dist --base-url https://example.com/

エージェントに「hreflang の設定を確認して」と頼むと、問題点と正しい <link> の書き方をまとめて報告します。

必要な環境

Python 3（標準ライブラリのみ）
URL を調べる場合は対象サイトへのネットワーク接続

注意点

通信は GET のみで、間隔をあけて取得します。サイトを変更したり、何かを送信したりはしません。
XML サイトマップ内の hreflang は読みません。
hreflang は表示する言語版を選ぶためのヒントで、順位を上げるものではありません。

English description

Checks hreflang on live URLs (GET only) or built HTML files: language codes, self-reference, return links, x-default and canonical consistency, reported per URL.

What it does

Validates hreflang on multilingual or multi-regional sites, page by page.

Reads <link rel="alternate" hreflang> in HTML and HTTP Link headers
Validates codes (ISO 639-1 language, optional script and region) and flags common mistakes such as jp, en-UK or en_US
Checks self-reference and x-default
Checks return links: if A lists B, B must list A, with the same set on both sides
Checks canonical consistency: canonicals pointing elsewhere, alternates that redirect or do not return 200
Can check a folder of built HTML files before deploying

How to use

python scripts/hreflang_check.py https://example.com/ https://example.com/en/ --follow --out hreflang.json
python scripts/hreflang_check.py --files ./dist --base-url https://example.com/

Ask your agent to check your hreflang setup; it reports problems and the corrected <link> block.

Requirements

Python 3 (standard library only)
Network access to the site when checking live URLs

Caveats

GET requests only, with a delay between them. Nothing on the site is changed or submitted.
hreflang declared only in XML sitemaps is not read.
hreflang helps search engines pick the right language version; it does not improve rankings.

インストール方法

ダウンロードしたZIPを展開します（中に hreflang-validator/ フォルダと SKILL.md があります）。
フォルダごと、使うエージェントのスキル置き場にコピーします。
- Claude：~/.claude/skills/（プロジェクト単位なら .claude/skills/）
- Hermes Agent：~/.hermes/skills/
- Codex：~/.agents/skills/／Cursor：~/.cursor/skills/
- Claude アプリ（claude.ai）：「カスタマイズ → スキル」からZIPをアップロード
エージェントを再起動し、スキル一覧に表示されることを確認します。

Windows・Mac 別、エージェント別のインストール手順