Guides · 4 min read · Updated 2026-09-08

Hreflang errors: the return-link problem and every other way multilingual SEO breaks

Hreflang tells search engines which language version to show. It fails silently when return links are missing, codes are invalid, or pages canonicalise elsewhere. How to audit every hreflang cluster on a site.

Hreflang is the annotation that tells Google and Yandex which version of a page to show to which users: German speakers in Switzerland get /de-ch/, everyone else who speaks German gets /de/, and nobody in Brazil is shown the Portuguese-for-Portugal page. When it works, the right page ranks in each market and the versions stop competing with each other as duplicates. When it fails, nothing visibly breaks; the wrong page simply ranks, or none of them do. Because the failure is silent, hreflang is wrong on most multilingual sites that have never been audited for it.

<link rel="alternate" hreflang="en-gb" href="https://example.com/en-gb/shoes/">
<link rel="alternate" hreflang="de" href="https://example.com/de/schuhe/">
<link rel="alternate" hreflang="x-default" href="https://example.com/shoes/">

The rules, all of them

Every page in a cluster lists every page in the cluster, including itself. If /en-gb/ points at /de/, then /de/ must point back at /en-gb/. A missing return link invalidates the pair; Google ignores annotations it can’t confirm from both sides.
Codes are ISO 639-1 language, optionally followed by ISO 3166-1 alpha-2 region. en, en-gb, de-ch, pt-br. Not en-uk (the region code is gb), not eng, not en_US with an underscore, not a region alone.
URLs are absolute and final. No relative paths, no redirects, no 404s, and the target must be indexable. An alternate that canonicalises to a different URL is a contradiction.
x-default names the page for users who match no listed language; usually a language selector or the English page. Optional but recommended.
Annotations live in one of three places: the HTML head, the HTTP Link header (for PDFs and other non-HTML), or the XML sitemap. A cluster can use any one; mixing them for the same page is asking for inconsistency.
Self-reference is required. A page that lists its alternates but not itself is incomplete.

The failures, in order of frequency

Missing return links. By far the most common. Usually the English site was annotated first and the translations were added later without updating the English pages, or a CMS generates alternates only for languages configured on that page. Truelint checks every pair in both directions and reports the ones that don’t reciprocate, with both URLs.

Invalid codes. en-uk, en-eu (Europe isn’t a country), zh-cn written as cn, ja-jp written as jp. Truelint validates each code against the language and region lists.

Alternates that aren’t indexable. The annotation points at a page that redirects, is noindexed, or canonicalises somewhere else. The cluster silently loses that language.

Canonical conflicts. The German page canonicalises to the English page (often from a “canonical to default language” plugin setting). That tells Google the German page is a duplicate, which contradicts the hreflang saying it’s the German version. The canonical wins and the German page stops ranking.

Wrong region defaults. /en/ annotated as en-us when it serves everyone; then British users are shown nothing, or shown the US page with US prices.

Multiple pages claiming the same code. Two URLs both annotated de in one cluster. Google keeps one at random.

Sitemap and head disagreeing. The sitemap says one cluster; the pages say another. Consistency matters more than which method you use.

Mixed hostnames and protocols. http:// alternates on an HTTPS site; www versions on a bare-domain site. Each mismatch is a redirect, and a redirected alternate is invalid.

Hreflang and canonicals together

The rule is simple: each language version canonicalises to itself, and lists all the others as alternates. Canonicals handle duplicates within a language (parameters, trailing slashes); hreflang handles equivalents across languages. If a plugin offers “canonical to the main language”, turn it off.

Hreflang and pagination, facets, parameters

Annotate the clean URL only. Page 2 of the German category has its own cluster with page 2 of the others, or no hreflang at all; don’t point page 2 at page 1 of another language. Parameter variants shouldn’t carry hreflang; they canonicalise to the clean URL, which does.

Auditing a whole site

Doing this by hand means opening every page in every language and comparing lists. A crawl does it for you: it collects every annotation from heads, headers and sitemaps, resolves every target, and checks every pair.

In Truelint, the Hreflang tab lists each page with its declared alternates and the status of each. The filters are the failure modes: missing return links, invalid codes, non-indexable targets, canonical conflicts, no self-reference, missing x-default. The detail pane for a page shows the full cluster with the status of every member, so a broken cluster can be fixed in one edit.

Fix by template, since the annotations are generated: correct the language map once, regenerate, re-crawl, confirm the error counts are zero.