What hreflang Actually Does
Hreflang is a declaration from your site to search engines saying, "this URL is the version of this page for users searching in language X (and optionally country Y)." Google does not use hreflang as a ranking signal directly — it uses it as a routing signal. When a Spanish-speaking user in Mexico searches for one of your pages, Google decides which of your URLs to surface in their SERP partly by reading your hreflang cluster. If the cluster is wrong, the wrong URL shows up; if the cluster is broken, Google may fall back to its own language detection, which is often worse than what you declared.
The mechanics are simple. Each URL declares a list of "alternate" siblings: same content, different audience. Each alternate is annotated with an hreflang attribute that names the audience by ISO 639-1 language code, optionally suffixed with an ISO 3166-1 region code. An optional x-default alternate handles the "everyone else" case. The cluster has to be bidirectional and the locale codes have to be standards-compliant for Google to trust the signal.
Where Hreflang Lives
There are three valid places to declare hreflang. First, in the HTML head as <link rel="alternate" hreflang="..." href="...">. Second, in the HTTP response headers via Link: <...>; rel="alternate"; hreflang="...". Third, in the XML sitemap as <xhtml:link rel="alternate" hreflang="..." href="..."/> elements inside each <url> entry. All three are equivalent for Google. Most CMS-driven sites use the HTML head approach because the per-page metadata is easier to template; large enterprise sites often use the sitemap approach because it concentrates all of the international declarations in one place that can be regenerated from a CMS export.
The Five Cluster-Level Mistakes
Most hreflang failures fall into one of five categories: missing return tags, missing self-references, invalid locale codes, duplicate locales, and missing x-default. The checker reports each of these as a distinct finding code so they can be triaged independently.
- Missing return tag (
MISSING_RETURN_TAG): URL A declares URL B as an alternate, but URL B does not declare A. Google requires the relationship to be bidirectional — without the return, the entire cluster is silently dropped.
- Missing self-reference (
MISSING_SELF_REFERENCE): URL A's hreflang block must include itself as an alternate. This is the rule most often violated by CMS templating bugs that emit the "other languages" list but forget to add the current one.
- Invalid locale (
INVALID_LOCALE): Values like en-USA, en-UK, br (instead of pt-BR), or english fail validation. Google rejects the malformed entry and may drop the entire cluster if too many entries are bad.
- Duplicate locale (
DUPLICATE_LOCALE): Two alternates within the same source URL claim the same locale but point to different URLs. The checker flags this with both target URLs so the conflict can be resolved.
- Missing x-default (
MISSING_X_DEFAULT): Strictly optional, but strongly recommended. Without an x-default Google has no fallback for users whose locale does not match any of your declarations. Reported as a warning by default, error when Require x-default is enabled.
Locale Code Standards
The language portion uses ISO 639-1 (two letters) or ISO 639-2 (three letters when no two-letter code exists). Examples: en, es, zh, fil. The optional region portion uses ISO 3166-1 alpha-2 (two letters, conventionally uppercase). Examples: en-US, es-MX, zh-CN. The separator is a hyphen, not an underscore. Common mistakes the checker catches: en_US (wrong separator), en-USA (three-letter region), en-UK (UK is not an ISO 3166-1 code — Great Britain is GB), and language-only entries with invalid codes like english or br.
x-default: The Fallback You Should Almost Always Declare
The x-default alternate tells Google, "if the user's locale does not match any of my explicit alternates, send them here." For most sites, the x-default points to the global landing page (often the English version, or an unbranded language picker). Without an x-default, Google has to guess. The guess is usually wrong, and the cost is sending Spanish-speaking visitors to the German URL because the German URL had the highest authority. The checker reports a missing x-default as a warning by default because some single-locale clusters legitimately do not need one, but for any cluster with three or more locales, x-default is effectively required.
Cluster Bidirectionality: The Most Expensive Mistake
The bidirectionality rule is the single most common cause of hreflang clusters being silently ignored by Google. The rule is exact: for every URL A in a cluster of size N, A must declare all N URLs (including itself) as alternates. If A declares B, but B does not declare A, the relationship is broken and Google may drop the entire cluster. The checker walks every cluster pair-by-pair and reports the exact missing return tag — not "cluster broken" but "URL A's hreflang block is missing a return tag pointing to URL B." That precision turns a vague Search Console "international targeting issue" warning into a one-line CMS fix.
Where Hreflang Auditing Fits In The Bigger SEO Picture
A clean hreflang cluster does not guarantee good international rankings — it guarantees that Google routes users to the URL you intended. The strongest international SEO programs combine: (a) a working hreflang cluster validated by a tool like this; (b) market-specific content rather than machine-translated boilerplate; (c) country-targeted Search Console properties so per-market performance can be tracked; (d) explicit canonicalization so duplicate-content rules do not collapse the cluster; (e) backlink profiles from local sources to establish topical authority in each market. The hreflang check is the cheapest 80% of that audit and the easiest one to run before any deploy.
Privacy: Why Local Validation Matters Here
Multilingual sitemap files routinely include URLs for staging environments, market-specific pre-launches, and gated content for specific countries. Uploading those to a third-party validator means those URLs end up in someone else's logs. This checker runs entirely in your browser tab — the XML or HTML never leaves the page. You can verify in DevTools that clicking Check triggers zero outbound requests. The same validation library is available open-source if you want to run it in CI; the web tool itself is fully self-contained.