Hreflang Errors: 7 Mistakes That Break International SEO

<!-- ✅ A complete cluster on https://example.com/en-gb/pricing (repeated identically on every member) -->
<link rel="alternate" hreflang="en-gb" href="https://example.com/en-gb/pricing">
<link rel="alternate" hreflang="en-us" href="https://example.com/en-us/pricing">
<link rel="alternate" hreflang="de"    href="https://example.com/de/preise">
<link rel="alternate" hreflang="x-default" href="https://example.com/pricing">
<link rel="canonical" href="https://example.com/en-gb/pricing">

<!-- ❌ Redirecting / internal alternates -->
<link rel="alternate" hreflang="en" href="http://www.example.com/en">
<link rel="alternate" hreflang="fr" href="https://www.example.com:443/fr/home.html">
<!-- ✅ The final, canonical URL every time -->
<link rel="alternate" hreflang="en" href="https://www.example.com/en/">
<link rel="alternate" hreflang="fr" href="https://www.example.com/fr/">

#!/usr/bin/env python3
"""hreflang_check.py: validate a page's hreflang cluster the way Google reads it.

Usage:
    python3 hreflang_check.py https://example.com/en/pricing [--max 25]

Standard library only. Reads hreflang from the HTML <head> and the HTTP Link header, then checks:
  1. codes: ISO 639-1 language [+ ISO 15924 script] [+ ISO 3166-1 alpha-2 region], e.g. en-GB not en-UK
  2. a self-referencing entry          3. an x-default entry
  4. one URL per language code        5. every alternate answers 200 directly (no redirect, no 4xx)
  6. alternates are indexable (no noindex) and canonical to themselves
  7. return links: each alternate lists this page back
Exit code 1 if any error was found.
"""
import argparse, re, ssl, sys, urllib.error, urllib.request
from urllib.parse import urljoin, urlsplit

LANGS = set("aa ab ae af ak am an ar as av ay az ba be bg bi bm bn bo br bs ca ce ch co cr cs cu cv cy da de dv dz ee el en eo es et eu fa ff fi fj fo fr fy ga gd gl gn gu gv ha he hi ho hr ht hu hy hz ia id ie ig ii ik io is it iu ja jv ka kg ki kj kk kl km kn ko kr ks ku kv kw ky la lb lg li ln lo lt lu lv mg mh mi mk ml mn mr ms mt my na nb nd ne ng nl nn no nr nv ny oc oj om or os pa pi pl ps pt qu rm rn ro ru rw sa sc sd se sg sh si sk sl sm sn so sq sr ss st su sv sw ta te tg th ti tk tl tn to tr ts tt tw ty ug uk ur uz ve vi vo wa wo xh yi yo za zh zu".split())
REGIONS = set("AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW".split())
UA = "Mozilla/5.0 (compatible; hreflang-check/1.0)"
LINK_TAG = re.compile(r"<link\b[^>]*>", re.I)
ATTR = lambda name: re.compile(r"\b" + name + r"\s*=\s*[\"']?([^\"'\s>]+)", re.I)
CTX = ssl.create_default_context()


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *a, **k):
        return None


def fetch(url):
    """Return (status, location, html, link_header) without following redirects."""
    opener = urllib.request.build_opener(NoRedirect, urllib.request.HTTPSHandler(context=CTX))
    try:
        with opener.open(urllib.request.Request(url, headers={"User-Agent": UA}), timeout=20) as r:
            return r.status, None, r.read(1_500_000).decode("utf-8", "replace"), r.headers.get("Link", "")
    except urllib.error.HTTPError as e:
        return e.code, e.headers.get("Location"), "", e.headers.get("Link", "") if e.headers else ""
    except Exception as e:
        return type(e).__name__, None, "", ""


def norm(u):
    p = urlsplit(u)
    return f"{p.scheme.lower()}://{(p.hostname or '').lower()}{p.path or '/'}" + (f"?{p.query}" if p.query else "")


def parse(base, html, link_header):
    head = html.split("</head>", 1)[0]
    tags, canonical, robots = [], None, ""
    for t in LINK_TAG.findall(head):
        rel = (ATTR("rel").search(t) or [None, ""])[1].lower()
        href = ATTR("href").search(t)
        if rel == "alternate" and ATTR("hreflang").search(t) and href:
            tags.append(("html", ATTR("hreflang").search(t).group(1), urljoin(base, href.group(1))))
        elif rel == "canonical" and href:
            canonical = urljoin(base, href.group(1))
    for m in re.finditer(r"<([^>]+)>\s*;[^,]*hreflang=\"?([^\";,]+)", link_header or ""):
        tags.append(("header", m.group(2), urljoin(base, m.group(1))))
    meta = re.search(r"<meta[^>]+name=[\"']robots[\"'][^>]*content=[\"']([^\"']+)", head, re.I)
    return tags, canonical, (meta.group(1).lower() if meta else "")


def code_problem(code):
    c = code.strip()
    if c.lower() == "x-default":
        return None
    if "_" in c:
        return f"'{c}' uses an underscore (use '{c.replace('_', '-')}')"
    parts = c.split("-")
    if parts[0].lower() not in LANGS:
        return f"'{c}': '{parts[0]}' is not an ISO 639-1 language code"
    rest = parts[1:]
    if rest and len(rest[0]) == 4 and rest[0].isalpha():   # ISO 15924 script, e.g. zh-Hant
        rest = rest[1:]
    if len(rest) > 1 or (rest and not (len(rest[0]) == 2 and rest[0].isalpha())):
        return f"'{c}' is not language[-Script][-REGION] (Google doesn't accept numeric regions like 419)"
    if rest and rest[0].upper() not in REGIONS:
        hint = " (the UK is 'GB')" if rest[0].upper() == "UK" else ""
        return f"'{c}': '{rest[0]}' is not an ISO 3166-1 region{hint}"
    return None


def audit(url, max_alt=25):
    res = {"url": url, "errors": [], "warnings": [], "alternates": []}
    status, loc, html, link = fetch(url)
    if status != 200:
        res["errors"].append(f"page itself returned {status}" + (f" → {loc}" if loc else ""))
        return res
    tags, canonical, robots = parse(url, html, link)
    res["tags"] = len(tags)
    if not tags:
        res["warnings"].append("no hreflang annotations found in <head> or Link header (sitemap annotations aren't checked)")
        return res
    methods = {m for m, _, _ in tags}
    if len(methods) > 1:
        res["warnings"].append("hreflang declared in both HTML and the HTTP header: Google says there's no benefit, and two copies can drift apart")
    for _, code, _ in tags:
        p = code_problem(code)
        if p:
            res["errors"].append(f"invalid code {p}")
    me = {norm(url)} | ({norm(canonical)} if canonical else set())
    if canonical and norm(canonical) != norm(url):
        res["errors"].append(f"page canonicalises to {canonical}, so its hreflang cluster is ignored on this URL")
    if not any(norm(h) in me for _, _, h in tags):
        res["errors"].append("no self-referencing hreflang entry")
    if not any(c.lower() == "x-default" for _, c, _ in tags):
        res["warnings"].append("no x-default (recommended fallback for unmatched languages)")
    by_code = {}
    for _, c, h in tags:
        by_code.setdefault(c.lower(), set()).add(norm(h))
    for c, urls in by_code.items():
        if len(urls) > 1:
            res["errors"].append(f"'{c}' points to {len(urls)} different URLs")
    targets = sorted({h for _, _, h in tags if norm(h) not in me})[:max_alt]
    for t in targets:
        st, loc, ahtml, alink = fetch(t)
        row = {"url": t, "status": st}
        if st != 200:
            res["errors"].append(f"alternate {t} returned {st}" + (f" → {loc}" if loc else "") + " (must be a direct 200)")
        else:
            atags, acanon, arobots = parse(t, ahtml, alink)
            if "noindex" in arobots:
                res["errors"].append(f"alternate {t} is noindex")
            if acanon and norm(acanon) != norm(t):
                res["errors"].append(f"alternate {t} canonicalises elsewhere ({acanon})")
            if not any(norm(h) in me for _, _, h in atags):
                res["errors"].append(f"no return link: {t} does not list this page")
                row["return"] = False
            else:
                row["return"] = True
        res["alternates"].append(row)
    return res


if __name__ == "__main__":
    ap = argparse.ArgumentParser()
    ap.add_argument("url")
    ap.add_argument("--max", type=int, default=25, help="max alternates to fetch")
    a = ap.parse_args()
    r = audit(a.url, a.max)
    print(f"{r['url']}: {r.get('tags', 0)} hreflang entries, {len(r['alternates'])} alternates fetched")
    for e in r["errors"]:
        print(f"  ✗ {e}")
    for w in r["warnings"]:
        print(f"  ⚠ {w}")
    if not r["errors"] and not r["warnings"]:
        print("  ✓ no problems found")
    sys.exit(1 if r["errors"] else 0)

https://www.corporate-group.example/: 2 hreflang entries, 2 alternates fetched
  ✗ no self-referencing hreflang entry
  ✗ alternate https://www.corporate-group.example:443/en canonicalises elsewhere (https://www.corporate-group.example)
  ✗ no return link: https://www.corporate-group.example:443/en does not list this page
  ✗ alternate https://www.corporate-group.example:443/home.html returned 301 → https://www.corporate-group.example (must be a direct 200)
  ⚠ no x-default (recommended fallback for unmatched languages)