hreflang

What hreflang actually does

When the same page exists in several languages, a search engine faces two questions: are these the same page, and which one should this particular searcher see? hreflang answers both. It groups the versions as translations of one another rather than near-duplicates competing for the same query, and it labels each one with the audience it was written for. Without it the engine guesses, and the visible symptom is a searcher in São Paulo landing on your English page and leaving.

It is worth being precise about what it does not do. hreflang will not make a page rank, will not consolidate ranking signals the way a canonical tag does, and will not rescue a translation nobody searches for. A page has to earn its position in its own language first; hreflang only makes sure the right version of an already-competitive page is the one shown. That distinction is why translating a site that ranks for nothing produces nothing — the decision of whether to translate at all is covered in should I translate my website for SEO.

How hreflang is implemented

There are three valid places to declare it, and you pick exactly one per site rather than mixing them. Whichever you choose, the same rules about codes and reciprocity apply.

• Link tags in the head — one alternate link element per version, present on every version. The most common approach, and the easiest to generate from a routing table.
• HTTP Link headers — the same information sent as a response header. This is the option for non-HTML files such as PDFs, which have no head to put tags in.
• XML sitemap entries — each URL in the sitemap lists its alternates. Useful for large sites, because it keeps the annotations in one file instead of on thousands of pages.
• An x-default value — the fallback for searchers whose language you do not target, usually pointing at your default-language page or a language selector. Optional, but it removes the ambiguity of who gets served when nothing matches.

The value is a language code from ISO 639-1, optionally followed by a region from ISO 3166-1 Alpha 2 — en, pt-br, zh-Hans. Language alone is valid; region alone is not. Every version must reference every other version *and itself*, and those references have to be reciprocal: if page A claims B is its Spanish version but B never points back, engines treat the claim as unconfirmed and ignore it.

Where hreflang goes wrong

Almost every failure is mechanical rather than editorial, which is why hreflang problems survive excellent translations and are usually found long after launch.

• One-way annotations — the most common error by a distance. Return links must be confirmed from both sides or the whole cluster is discarded.
• Invented or mismatched codes — en-uk is not valid, because the region code for the United Kingdom is gb. A single malformed value invalidates that annotation silently.
• Assuming the URL token is the language tag — a site can perfectly reasonably serve Brazilian Portuguese from a /pt path while annotating it pt-BR. Deriving the tag from the path is a quiet source of wrong labels.
• Pointing at URLs that redirect, 404, or carry noindex — the target has to be the live, indexable version, otherwise the signal is dropped.
• Redirecting visitors automatically by browser language — this defeats the annotation entirely, since a crawler bounced to one version never reaches the others it was told about.