Best hreflang Checker Tools 2027: Catch Broken Language Tags

The best hreflang checker tools for 2027 and the six errors that break international SEO, each planted in a test site and caught by a free script.

· BugViso Team

11 min read

The best hreflang checker for 2027 is one that follows the links, not just reads the tags: it must confirm that every alternate page links back, returns a 200, uses a valid language code and doesn't canonicalise somewhere else. A site crawler such as BugViso catches code and self-reference errors across every page, and the free script in this post adds the return-link and status checks for any set of URLs.

Google ignores hreflang tags unless both pages point at each other, so one missing return tag can silently switch off a language version. To show what a checker has to catch, we built a small test site with six common hreflang errors and ran the script against it. It flagged all six.

By the end you will know the rules Google applies to hreflang, which tool checks which rule, and how to test any page's language set for free.

Data used: a local test site built on 2026-11-16 with an English page linking seven language versions, seeded with six errors: an invalid region (en-uk), an invalid language (jp), a missing return tag, an alternate that redirects, an alternate that canonicalises to another language, and relative alternate URLs. The rules come from Google's documentation on localized versions of your pages, fetched the same day. We make BugViso, one of the tools listed.

The hreflang Rules a Checker Must Test

Google's documentation sets five rules, and a checker that skips any of them misses real errors. Each one below is quoted from or based on Google's localized versions guide.

  1. Every version lists itself and all the others. "Each language version must list itself as well as all other language versions."
  2. Links must go both ways. "If two pages don't both point to each other, the tags will be ignored." This stops other sites from claiming your pages as their alternates.
  3. Codes must be valid. The language is an ISO 639-1 code, optionally followed by an ISO 3166-1 Alpha 2 region: en-GB, not en-UK; ja, not jp.
  4. URLs must be fully qualified. https://example.com/foo, not /foo.
  5. x-default names the fallback. Use it for a language selector or the page for unmatched languages.

Google accepts hreflang in HTML <link> tags, HTTP headers or the XML sitemap, and treats the three methods as equivalent. Pick one and use it everywhere.

Six Planted Errors, Six Flagged

We built a seven-language page set with six common mistakes and pointed the checker at it. Every one was reported, with the reason.

Seeded errorWhat Google does with itFlagged
en-uk instead of en-gbIgnores the tag (UK isn't an ISO 3166 code)Yes
jp instead of jaIgnores the tag (jp is a country, not a language)Yes
German page doesn't link backIgnores the pairYes
French alternate returns a 301The tag points at a URL that isn't the final pageYes
Spanish alternate canonicalises to EnglishConflicting signals; Google may drop the Spanish versionYes
Relative URLs (/it/)Not fully qualified, against Google's guidelinesYes

The three link-level errors (no return tag, a redirect, a cross-language canonical) only appear when a checker fetches the alternate pages. A tool that reads the tags on one page can't see them, and they are the ones that most often switch off a whole language version.

The 5 Best hreflang Checkers

ToolBest forChecks return linksPrice
BugViso site auditCode format and self-reference on every crawled pageNoFirst report free
The script belowThe full rule set for any page and its alternatesYesFree
Search Console URL InspectionWhich canonical Google chose for each language versionIndirectlyFree
A crawl export and a spreadsheetMapping return links across a large siteYes, by handFree
View sourceSeeing exactly which tags a page sendsNoFree

BugViso: format and self-reference across a site

BugViso parses every <link rel="alternate" hreflang> tag on each crawled page, checks the language and region format, and confirms each page lists itself. Because it runs on every page, a template that drops the self-reference or uses a wrong code shows up across the whole section at once. Where others go further: it doesn't fetch each alternate to confirm the return link, and it reads HTML tags only, not hreflang in HTTP headers or sitemaps. Use the script for those checks.

The free script: the full set of rules

The script below fetches a page, reads its hreflang set, then fetches every alternate to check its status, its return link and its canonical. It's the tool behind the table above, and it exits with an error code when it finds a problem, so you can run it in a deploy check.

Search Console URL Inspection: Google's verdict

URL Inspection shows the canonical Google selected for a URL. If the Spanish page's Google-selected canonical is the English page, Google has folded the two together, usually because of a canonical tag, near-identical content, or broken hreflang. Google's URL Inspection documentation explains each field.

A crawl export and a spreadsheet: the large-site method

For thousands of pages, export every page's hreflang tags from a crawl into a sheet with one row per pair, then check that each A → B row has a matching B → A row. It is slow but complete, and it's how most international audits are done at scale.

View source: what the page really sends

Check the raw HTML, or the Link response header if you use the header method, when a tool and your CMS disagree. Tags added by JavaScript after load may be missed by some crawlers.

How to Fix the Errors a Checker Finds

Most hreflang errors come from generating tags page by page instead of from one shared mapping. Fix the source, not each page.

html
<!-- ✅ The same block on every version: itself, all others, x-default, absolute URLs -->
<link rel="alternate" hreflang="en-us" href="https://example.com/en/">
<link rel="alternate" hreflang="en-gb" href="https://example.com/uk/">
<link rel="alternate" hreflang="de" href="https://example.com/de/">
<link rel="alternate" hreflang="ja" href="https://example.com/ja/">
<link rel="alternate" hreflang="x-default" href="https://example.com/en/">
  • Build the set once. Generate every page's tags from one list of language URLs, so all versions always carry the same block.
  • Point at final URLs. If /fr/ redirects to /fr-fr/, list /fr-fr/. Our guide to finding and fixing redirect chains covers the redirect side.
  • Self-canonicalise each version. Each language page's canonical should be itself, never another language.
  • Check codes against the standard. en-GB, ja, zh-TW, pt-BR. When in doubt, look the code up rather than guessing from a country name.

The full list of error types and what each does to rankings is in our guide to hreflang errors.

Run It Yourself: Check a Page's Whole hreflang Set

This script reads a page's hreflang tags, flags relative URLs and common wrong codes, then fetches each alternate to check status, return link and canonical. It uses only Python's standard library.

python
#!/usr/bin/env python3
"""Check a page's hreflang set: valid codes, self-reference, return links, status, canonicals.

Usage: python3 hreflang_check.py <url>
"""
import re
import sys
import urllib.error
import urllib.request
from urllib.parse import urljoin

# shortcut: catches the common mistakes, not every invalid ISO code; add a full list if you need it.
WRONG = {"en-uk": "en-gb", "jp": "ja", "cn": "zh", "kr": "ko", "gr": "el", "se": "sv",
         "dk": "da", "cz": "cs", "ua": "uk", "en-eu": "(no EU region)", "es-la": "(no LA region)"}
CODE = re.compile(r"^(x-default|[a-z]{2,3}(-[a-z]{4})?(-([a-z]{2}|\d{3}))?)$")


def fetch(url):
    """Return (status, final_url, html) without following redirects silently."""
    class NoRedirect(urllib.request.HTTPRedirectHandler):
        def redirect_request(self, *a, **k):
            return None
    opener = urllib.request.build_opener(NoRedirect)
    try:
        r = opener.open(urllib.request.Request(url, headers={"User-Agent": "hreflang-check/1.0"}), timeout=20)
        return r.status, url, r.read().decode("utf-8", "replace")
    except urllib.error.HTTPError as e:
        return e.code, e.headers.get("Location") or url, ""


def alternates(html):
    out = {}
    for tag in re.findall(r"<link[^>]+>", html, re.I):
        if re.search(r'rel=["\']?alternate', tag, re.I) and "hreflang" in tag.lower():
            lang = re.search(r'hreflang=["\']?([^"\'\s>]+)', tag, re.I).group(1).lower()
            href = re.search(r'href=["\']?([^"\'\s>]+)', tag, re.I).group(1)
            out[lang] = href
    return out


def canonical(base, html):
    m = re.search(r'<link[^>]+rel=["\']?canonical["\']?[^>]*href=["\']?([^"\'\s>]+)', html, re.I)
    return urljoin(base, m.group(1)) if m else None


def check(url):
    problems = []
    _, _, html = fetch(url)
    raw = alternates(html)
    problems += [f"{lang}: {href} is relative; Google needs fully-qualified URLs"
                 for lang, href in raw.items() if not href.startswith(("http://", "https://"))]
    alts = {lang: urljoin(url, href) for lang, href in raw.items()}
    if not alts:
        return [f"{url}: no hreflang tags"]
    if url not in alts.values():
        problems.append(f"{url}: no self-referencing hreflang")
    for lang, href in alts.items():
        if lang in WRONG:
            problems.append(f"{lang}: wrong code, use {WRONG[lang]}")
        elif not CODE.match(lang):
            problems.append(f"{lang}: not a valid hreflang code")
        if href == url:
            continue
        s, loc, other = fetch(href)
        if s != 200:
            problems.append(f"{lang}: {href} returns {s}" + (f" -> {loc}" if 300 <= s < 400 else ""))
            continue
        if url not in (urljoin(href, h) for h in alternates(other).values()):
            problems.append(f"{lang}: {href} does not link back (no return tag)")
        canon = canonical(href, other)
        if canon and canon != href:
            problems.append(f"{lang}: {href} canonicalises to {canon}")
    return problems


if __name__ == "__main__":
    found = check(sys.argv[1])
    print("\n".join(found) or "hreflang set looks consistent")
    sys.exit(1 if found else 0)

The output against our seeded test site, unedited:

text
en-uk: wrong code, use en-gb
de: http://127.0.0.1:8765/de/ does not link back (no return tag)
jp: wrong code, use ja
fr: http://127.0.0.1:8765/fr/ returns 301 -> /fr-fr/
es: http://127.0.0.1:8765/es/ canonicalises to http://127.0.0.1:8765/en/

Run it on one page from each language and each template, not just the home page. It reads HTML tags only; if you declare hreflang in your sitemap or HTTP headers, check those separately. The code list catches the usual mistakes rather than every invalid ISO code, as the comment in the script says.

How BugViso Validates hreflang Across a Site

BugViso's technical SEO engine reads the hreflang tags on every crawled page, enforces the language and region format, and checks that each page includes a self-referencing tag. The crawl runs in a real browser, so tags rendered by JavaScript frameworks are included.

The same engine checks canonicals and duplicate content, which are the usual reasons a language version gets folded into another. Findings land in the ranked fix list with a developer-facing fix, and the PDF report groups them for the client. The technical SEO feature page lists the checks.

Frequently Asked Questions

How do I check if hreflang is working?

Check three things for each language version: the page lists itself and every other version with valid codes, every listed page links back, and every listed URL returns a 200 and is its own canonical. The script in this post checks all three; Search Console's URL Inspection shows which canonical Google chose.

What happens if hreflang return tags are missing?

Google ignores the pair. If the German page doesn't link back to the English page, Google treats the hreflang annotation between them as if it weren't there, so the German page may not be shown to German searchers. Missing return tags are the most common hreflang error.

Is hreflang en-uk or en-gb?

Use en-gb. The region part of hreflang is an ISO 3166-1 Alpha 2 country code, and the code for the United Kingdom is GB. uk on its own is the language code for Ukrainian, which is why en-uk is invalid.

Do I need x-default?

It isn't required, but Google recommends it for a fallback page, such as a language selector or the version to show when no other language matches. Without it, Google chooses a version for unmatched users itself.

Should hreflang go in the HTML, HTTP headers or sitemap?

Google treats all three as equivalent. HTML tags are easiest to check; sitemaps scale better for very large sites; HTTP headers suit non-HTML files such as PDFs. Pick one method and use it consistently, because mixing them makes errors harder to find.

The hreflang Check Most Tools Skip

Reading the tags on one page tells you very little; following each one to confirm it links back, loads and isn't canonicalised away is what proves the set works. Run the script on one page per language and template, and run a BugViso audit to catch format and self-reference errors on every page.

Written by

· BugViso Team

Kazi writes BugViso’s guides on website audits, Core Web Vitals, technical SEO, accessibility and AI search. The data in them comes from audits BugViso runs in a real Chromium browser, including our 219-site study of website health.

Found this useful? Share it.

Summarise with AI

Open this guide in your assistant.

Follow BugViso

New guides and audit data as we publish them.

AI visibility tracker

Is your brand in AI answers?

See how often AI assistants mention you, cite your site and rank you against your competitors.

  • ChatGPT
  • Gemini
  • Perplexity
  • Claude
  • AI Overviews
See how it works

See where your site stands

Run a free BugViso audit for SEO, speed, accessibility and AI search readiness — with fixes you can ship today.