A site with English, Polish and Dutch versions of the same guide has to tell Google which page is which language, or Google guesses, and often guesses the English page for a Dutch searcher. hreflang is how you tell it. It is also one of the most silently broken tags on the web, because a single missing return link makes Google discard the whole set without a warning.
What does this check detect?
Answer. For every page with alternate language versions: does it reference itself, is there an x-default, does every listed alternate list this page back, and are there languages the page exists in but does not declare.
Moonleap groups the pages in your inventory into language clusters (by the hreflang tags they carry and by URL pattern such as /nl/, /pl/), then checks each cluster against Google's rules. The finding lists the pages and which rule each one breaks. On the site in the case below, 16 language pages were checked on 7 September 2026 and passed all of them; earlier in the summer the same site had clusters where the Polish page listed the English one but not the reverse.
Why does one missing link break the whole set?
Answer. Because Google requires return links: if page A says B is its Dutch version, B must say A is its English version, or Google ignores the annotation on both.
Google's documentation is explicit about it. The reasoning is anti-abuse: without the requirement, anyone could claim your page as their alternate. The consequence is that hreflang is all-or-nothing per cluster. A set of five languages where one page forgot the tag is, to Google, a set with no hreflang at all.
The other two rules: every page lists itself (a Dutch page includes hreflang="nl" pointing at its own URL), and one page is marked x-default as the fallback for languages you do not serve. The x-default is optional in the spec and recommended in the docs; skipping it means a French searcher lands on whichever version happens to rank.
What is the fix?
Answer. Generate the tags from one list of translations in the layout, so a page cannot know about a sibling the sibling does not know about.
The bug is almost always hand-written tags, one page at a time. The cure is one data structure and one loop. SvelteKit, in the layout that wraps translated pages:
<svelte:head>
{#each alternates as a}
<link rel="alternate" hreflang={a.lang} href={a.url} />
{/each}
<link rel="alternate" hreflang="x-default" href={alternates[0].url} />
</svelte:head>
where alternates is the full list for this cluster, including the current page, computed from your translations table. Next.js does the same through metadata.alternates.languages in the page or layout. In both, the list comes from data, so adding a Dutch translation adds the Dutch link to every sibling at once.
Two details that bite: use absolute URLs (https://…), and use the language code Google expects (nl, pt-BR, en-GB; not en_GB, not nl-nl for a generic Dutch page).
How do you verify it?
Answer. Fetch each page in the cluster and check that every one lists all the others plus itself, then look at Search Console's International Targeting report after a recrawl.
From a terminal, for one cluster:
for u in https://<site>/guide https://<site>/nl/gids https://<site>/pl/przewodnik; do
echo "== $u"; curl -s "$u" | grep -o 'hreflang="[^"]*" href="[^"]*"'
done
Every block should print the same set of URLs. In Search Console, Legacy tools, International Targeting lists "no return tags" errors per page; they clear as Google recrawls.
FAQ
Do I need hreflang if each language is on its own domain?
Yes. The tags work across domains; the return-link rule applies the same way.
Should hreflang go in the HTML, the HTTP header or the sitemap?
Any one of the three. Pick one and be consistent; mixing them is a common source of missing return links.
Does hreflang help with AI search?
Indirectly. AI Overviews and answer engines pull from the indexed page that matches the searcher's language; a correct cluster makes that the right page.
Sources
- Google, "Tell Google about localized versions of your page" https://developers.google.com/search/docs/specialty/international/localized-versions
- Case, omniroom.ai, 16 EN/PL/NL pages, hreflang cluster check on 7 September 2026 (Moonleap inventory audit)