Hreflang for multilingual websites: a practical guide
How hreflang works, the rules that make it valid, the most common mistakes and how to implement it reliably in a modern multilingual website.
Hreflang tells search engines that several URLs are versions of the same page for different languages or regions. When it works, users land on the version in their language. When it's broken, the wrong version can rank, or several versions compete with each other.
What hreflang actually does
Hreflang is an annotation that connects equivalent pages. It does not make a page rank, and it is a signal rather than a directive: search engines may ignore annotations they consider inconsistent.
You can declare it in three places. Pick one and use it consistently:
<link rel="alternate" hreflang="…" href="…">elements in the HTML<head>LinkHTTP headers (useful for non-HTML files such as PDFs)xhtml:linkentries in an XML sitemap
The rules that make it valid
- Use valid codes. The language is an ISO 639-1 code (
en,it,pt). An optional region uses ISO 3166-1 Alpha-2 (pt-BR,en-GB). A region alone is invalid, anden-UKis a classic mistake: the correct code isen-GB. - Be reciprocal. If page A points to page B, page B must point back to page A. Missing return links are the most common reason annotations get ignored.
- Self-reference. Each page includes itself in its own hreflang set.
- Point to canonical, indexable URLs. Every URL in the cluster should return a 200 status, be indexable and declare itself as canonical. Pointing hreflang at redirected,
noindexor non-canonical URLs breaks the cluster. - Add
x-default. It defines the fallback for users whose language or region doesn't match any version. This is often a language selector or the main market.
A minimal, correct example
<link rel="canonical" href="https://example.com/it/servizi/" />
<link rel="alternate" hreflang="en" href="https://example.com/en/services/" />
<link rel="alternate" hreflang="it" href="https://example.com/it/servizi/" />
<link rel="alternate" hreflang="pt-BR" href="https://example.com/pt-br/servicos/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/services/" />
Note that the canonical points to the page itself, not to the English version. Canonicalising every language to one version tells search engines the translations are duplicates, which is the opposite of what you want.
Common mistakes
- Canonical to another language. Each language version must be its own canonical.
- Automatic redirects based on IP or browser language. Crawlers may never see some versions. Suggest a language instead of forcing a redirect.
- Partial translations. A page with only the navigation translated is not a real alternate. Translate the main content.
- Mismatched URLs. Trailing slashes,
httpvshttpsorwwwvs non-wwwdifferences create references to URLs that redirect.
Implementing it in a modern framework
In frameworks like Next.js, generate canonical and hreflang from the same route map that produces your localized URLs. That way a new page or translated slug can't be published with a broken cluster. On this site, a single function builds the canonical, every alternate and x-default for each page, and unit tests check that each cluster is complete and reciprocal.
How to verify
Crawl the site with a tool that reports hreflang (most SEO crawlers do), check that every cluster is complete and reciprocal, and monitor Search Console for indexing issues on each language version. Fixing hreflang is rarely glamorous, but on multilingual sites it is often one of the highest-leverage technical tasks.