---
title: Your hreflang Tags Are Probably Broken, and Nobody Is Testing Them
description: Hreflang fails silently, and by the time Search Console tells you, the wrong page has been ranking in the wrong market for weeks. Here is how to validate it in CI with five binary assertions.
author: LETSGROW Dev Team
date: 2026-10-31
category: SEO
tags: ["Hreflang", "International SEO", "Technical SEO", "CI/CD", "SEO Automation"]
url: "https://letsgrow.dev/blog/hreflang-validation-ci-international-seo-regressions"
---
# Your hreflang Tags Are Probably Broken, and Nobody Is Testing Them

Hreflang is the most fragile piece of international SEO, and almost every team treats it as a set-and-forget task. It is not. It is a bidirectional contract between pages, and a contract between hundreds of URLs breaks the moment someone renames a slug, retires a locale, or ships a template change. The fix is not a better plugin. The fix is to treat hreflang like code: validate it automatically, in CI, on every deploy.

## Why hreflang Fails Silently

Hreflang has no error state in the browser. A broken annotation renders exactly like a working one. Google Search Console reports some problems, but it lags by days or weeks, and it only flags what it has already crawled. By the time you see the warning, the wrong-language page has been ranking in the wrong market for a month.

The core problem is reciprocity. If your English page declares a German alternate, the German page must declare the English page back. If either side is missing, search engines are free to ignore the whole cluster. Multiply that by every page and every locale and you have a validation problem that no human review process can keep up with.

Three things cause most breakage. Content teams change a URL in one locale and forget the others. Developers add a locale to the router but not to the head template. And redirects quietly turn a valid alternate into a 301, which is not a valid hreflang target.

::compare-table
title: "Common hreflang Failures and How to Catch Them"
columns: ["Failure", "What Happens", "Automated Check"]
rows:
  - ["Missing return tag", "Cluster is ignored", "For every alternate, fetch it and confirm it links back"]
  - ["Alternate returns 301 or 404", "Annotation is discarded", "Assert HTTP 200 on every alternate URL"]
  - ["No self-referencing tag", "Inconsistent cluster signals", "Assert each page lists its own URL"]
  - ["Wrong language or region code", "Page targets the wrong market", "Validate codes against ISO 639-1 and ISO 3166-1"]
  - ["Canonical points elsewhere", "Hreflang conflicts with canonical", "Assert canonical equals the page's own URL"]
  - ["Missing x-default", "No fallback for unmatched users", "Assert exactly one x-default per cluster"]
::

## The Five Assertions That Matter

You do not need a vendor platform. You need a script that runs five assertions against every URL in your sitemap.

First, every page lists a self-referencing hreflang entry. Second, every alternate URL returns a 200 with no redirect hops. Third, every alternate links back to the original page with the correct language code. Fourth, language and region codes are valid, which means lowercase language, uppercase region, and no invented codes like en-UK. Fifth, the canonical URL on each page matches the page itself, so hreflang and canonical never contradict each other.

Notice what is missing from that list: opinions. Every one of these is a binary check. That is exactly why it belongs in a test suite rather than a quarterly audit spreadsheet.

## Build the Validator in an Afternoon

The implementation is simpler than most teams expect. Pull your sitemap and extract every URL. For each URL, fetch the HTML and parse every link tag with rel set to alternate and an hreflang attribute. Build a map of page to declared alternates. Then run the five assertions over that map.

The reciprocity check is the only one that needs the full map. For each page A that declares page B, confirm that B declares A with the matching code. This is a simple set comparison, and it runs in memory once the crawl finishes. For a site with a few thousand URLs, concurrent fetching with a limit of ten to twenty requests finishes in minutes.

Two implementation details save you pain later. Fetch with redirects disabled, so a 301 shows up as a failure instead of being silently followed. And parse the rendered HTML, not just the raw response, if your hreflang tags are injected client side. Better still, move them server side, because search engines treat late-injected annotations as unreliable.

If your hreflang lives in the XML sitemap instead of the page head, the same logic applies. Parse the xhtml:link entries in each URL block and run the same assertions. Pick one location and stay with it. Mixing head tags and sitemap annotations is how contradictions creep in.

## Wire It Into CI and Production Monitoring

A validator you run by hand is a validator you forget to run. Put it in two places.

In CI, run it against the preview deployment for every pull request that touches routing, templates, or content models. Fail the build on any assertion error. This catches the developer who adds a locale and forgets the head template before it reaches production.

In production, run it nightly against the live site and alert on regressions. This catches the failures CI cannot see, such as a content editor changing a slug in the CMS. Send the alert to the channel your web team already watches, with the offending URL and the specific assertion that failed. An alert that says hreflang is broken is noise. An alert that says the German alternate for /pricing returns a 301 is a ticket.

## What to Do This Week

Run a one-time crawl of your current site and count the reciprocity failures. That number is your baseline, and it will probably be uncomfortable. Fix the failures that affect your highest-traffic locales first. Then commit the validator to your repository and add it to your pipeline before you ship the next release.

International SEO rewards the teams that make correctness automatic. Hreflang is the cheapest place to start, because every failure is detectable, every check is binary, and the cost of a miss is a market full of visitors landing on the wrong page.
