Hreflang: implementation, common errors and checks

What hreflang does, and what it does not

Hreflang declares a relationship between several URLs carrying the same content in different languages or regions. Google's documentation on localised versions describes three typical cases: a translated template while the main content stays in one language, identical content with regional variations, and a fully translated site.

Two limits are stated in plain terms in that documentation. First, Google uses neither hreflang nor the HTML lang attribute to determine a page's language: it relies on its own algorithms. Second, localised versions count as duplicates only when the main content is not translated. A correct hreflang therefore does not fix an English page where only the menus were translated.

If the issue involves two close English pages, it is not an international problem: read our piece on SEO cannibalization before touching annotations. And when URLs genuinely need consolidating, the canonical does that job through a separate mechanism.

Head, HTTP headers or sitemap: which one?

The one your stack can maintain over time. Google states the three methods are equivalent from its point of view, and that using all three at once brings no search advantage while multiplying the implementations to manage.

Tags in the head

The natural choice for a page-rendered site, including when the tags are injected by the application. On digitalfranck.com each English article declares its French counterpart and itself in the head, and the French article does the reverse: that is the implementation running on this page, verifiable in its source. The known constraint is that the link set must be identical on every version and sit inside a well-formed head.

HTTP headers

Useful for non-HTML files. A white paper in PDF published in two languages is signalled with a Link header listing every variant, including the requested version. For a SaaS, this is the one case where the method is genuinely required.

XML sitemap

The most economical method once the number of pairs grows or the head is already crowded. Each url element gets one xhtml:link child per version, the page itself included, with the xmlns:xhtml namespace declared. Google notes that these child elements do not count towards the sitemap URL limit, and that the general sitemap guidelines also apply to sitemap extensions.

Why your annotations get ignored

Because a documented condition is not met, not because Google is slow. Two causes recur in the official documentation, and both can be checked in minutes.

The missing return link

If page A declares page B without B declaring A, the annotations may be ignored or misinterpreted. Google explains why: without that reciprocity, any site could arbitrarily declare one of your pages as its own variant. In practice the defect shows up as soon as one language is produced by a different template or a different CMS than the original language.

The documentation allows a useful trade-off when a complete set becomes unmanageable: some languages can be omitted on some pages, and the pairs that do point at each other are still processed. The stated priority is explicit, link new languages bidirectionally to the original or main language before linking the new variants to one another.

Invalid codes

The first code is the language in ISO 639-1 format, optionally followed by a region in ISO 3166-1 Alpha 2 format. A region alone is not enough: Google does not derive the language from the country. The example in the documentation is blunt, be means Belarusian rather than Belgium, hence fr-be, nl-be or de-be depending on the dialect targeted. Reserved codes such as EU, UN or UK have no effect in Search.

Other formal points worth respecting: absolute URLs including the protocol, never a relative path, and no mixing of hreflang annotations with other attributes such as media inside the same link tag.

When several templates produce the two languages and the sets diverge by template, a technical SEO project on indexing and URL signals fixes the cause at template level rather than page by page.

x-default: useful, but not everywhere

The reserved x-default value marks the page to serve when no declared version matches a user's settings. It takes no language code, since the language of that page is not the criterion. Google notes it was designed for language selection pages and redirecting homepages, and that this is where it works best.

For a SaaS with no selector, the decision is to nominate the most complete or most commercially legitimate version as the fallback. Google also recommends a region-free catch-all URL when several variants target the same language in different countries, for example a generic en page above en-ie, en-ca and en-au.

The checks to run before release

Hreflang is verified on the rendered output, not on the developer's intent. Five checks rule out almost every documented defect.

• Open the rendered source of both versions and confirm each declares the other and itself, with absolute URLs.
• Compare the sets line by line: a variant present on one side and absent on the other is a defect, not a rounding error.
• Validate every code against the ISO 639-1 and ISO 3166-1 Alpha 2 lists, treating UK as an error.
• Check that only one method is live, and that an old sitemap does not contradict the tags in the head.
• Check each version's canonical: it must point to that version, not to another language's version.

Google no longer provides an international targeting report in Search Console; its troubleshooting documentation points to third-party tools instead, while stating they are neither maintained nor verified by Google. Manual pair checking therefore remains the reference, and it is short when a site has only two languages.

When the issue goes beyond annotations and touches the structure of both versions, an SEO audit that prioritises bottlenecks avoids treating translation, indexing and architecture as one single job.

Translated content alone does not earn a version

This is the most frequently ignored limit. Perfect hreflang gives an English version no reason to exist if it mirrors a French page word for word without adapting the examples, the evidence or the search intents of the target market.

Google's documentation on managing multi-regional and multilingual sites handles the upstream question: which URL structure, which targeting, which version for which audience. Those decisions come before the attribute, and that is where a multilingual site's real performance is decided.

For a SaaS, the English version usually serves a different demand, with different competitors and different queries. A content strategy built market by market produces more than a clean translation with correct annotations.

About the author

Franck Gordi

Independent SEO and GEO consultant for B2B SaaS. He helps software companies become visible on Google and cited by AI engines.

LinkedIn →