hreflang validator for live URLs and HTML files

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.