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.
Kazi Khalid Hasan Tamim · 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.
- Every version lists itself and all the others. "Each language version must list itself as well as all other language versions."
- 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.
- Codes must be valid. The language is an ISO 639-1 code, optionally followed by an ISO 3166-1 Alpha 2 region:
en-GB, noten-UK;ja, notjp. - URLs must be fully qualified.
https://example.com/foo, not/foo. x-defaultnames 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 error | What Google does with it | Flagged |
|---|---|---|
en-uk instead of en-gb | Ignores the tag (UK isn't an ISO 3166 code) | Yes |
jp instead of ja | Ignores the tag (jp is a country, not a language) | Yes |
| German page doesn't link back | Ignores the pair | Yes |
| French alternate returns a 301 | The tag points at a URL that isn't the final page | Yes |
| Spanish alternate canonicalises to English | Conflicting signals; Google may drop the Spanish version | Yes |
Relative URLs (/it/) | Not fully qualified, against Google's guidelines | Yes |
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
| Tool | Best for | Checks return links | Price |
|---|---|---|---|
| BugViso site audit | Code format and self-reference on every crawled page | No | First report free |
| The script below | The full rule set for any page and its alternates | Yes | Free |
| Search Console URL Inspection | Which canonical Google chose for each language version | Indirectly | Free |
| A crawl export and a spreadsheet | Mapping return links across a large site | Yes, by hand | Free |
| View source | Seeing exactly which tags a page sends | No | Free |
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.
<!-- ✅ 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.
#!/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:
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
Kazi Khalid Hasan Tamim · 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.
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 where your site stands
Run a free BugViso audit for SEO, speed, accessibility and AI search readiness — with fixes you can ship today.