What Is Hreflang?
Hreflang is an HTML attribute that tells search engines which language or regional version of a page to serve to a specific user. When a site publishes the same content in English, Spanish, and German, hreflang signals to Google that these pages are alternates of one another rather than duplicate content, and it maps each version to the right audience.
The attribute pairs a URL with a language and (optionally) region code, written as hreflang="en-us" or hreflang="fr". The language portion uses an ISO 639-1 code, and the optional region uses an ISO 3166-1 Alpha-2 code. So pt-br means Portuguese as spoken in Brazil, while pt-pt means Portuguese in Portugal.
Hreflang does not change rankings directly. It is a targeting signal, not a ranking factor. Its job is to make sure a Spanish-speaking searcher in Mexico lands on the Spanish page instead of the English one, which improves engagement and cuts down on the wrong-language bounce that quietly erodes performance. Hreflang is part of the broader technical SEO layer that controls how engines crawl, index, and serve your pages.
Hreflang Syntax and Code Example
Hreflang syntax always describes a set of alternate URLs, with each entry naming a URL and the language or region it serves. The cleanest place to start is the HTML head, where each version of the page references every other version, including itself.
Here is a working example for a page available in US English, UK English, and French:
html
<link rel="alternate" hreflang="en-us" href="https://example.com/page" />
<link rel="alternate" hreflang="en-gb" href="https://example.com/uk/page" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />Two rules make or break this block. First, every page in the set must include the full list — the US page, the UK page, and the French page all carry the same four tags. This is the return-tag requirement: if page A points to page B but page B does not point back to A, Google ignores the relationship.
Second, use `x-default` to name the fallback version for users whose language or region you do not explicitly target. It is optional but strongly recommended for the page a global homepage redirector or unmatched user should see.
Hreflang and canonical tags work together, not against each other. Each language version should self-canonicalize (point its canonical at itself), never at another language. Pointing a French page's canonical at the English version tells Google to drop the French page entirely.
Where to Put Hreflang Tags
Hreflang tags can live in three places, and you should pick exactly one method per site to avoid conflicting signals. The three options are the HTML head, the HTTP response header, and the XML sitemap.
- HTTP headers — a
Link:header in the server response. The only option for non-HTML files like PDFs, where there is no head to edit. - XML sitemap —
<xhtml:link>entries inside your sitemap. Best for large sites because it keeps page markup lean and centralizes the mappings in one file you can validate.
| Method | Best for | Pros | Cons |
|---|---|---|---|
| HTML head <link> | Most HTML pages, small to mid sites | Easy to inspect and debug | Bloats markup with many languages |
| HTTP Link header | Non-HTML files like PDFs | Only option for files with no head | Hard to inspect; needs server config |
| XML sitemap | Large sites, hundreds of URLs | Lean pages, one file to audit | Requires correct sitemap structure |
For most sites I recommend the XML sitemap method once you pass a few hundred URLs. It scales cleanly, keeps your HTML payload small, and lets you audit every relationship in one document. If you are building or auditing your sitemap, start with how to create an XML sitemap.
Whichever method you choose, use absolute URLs (full https:// paths), match your canonical URLs exactly, and never mix two methods on the same page. Mixed signals are one of the fastest ways to confuse the implementation.
Common Hreflang Mistakes
Common hreflang mistakes almost always trace back to broken bidirectionality or invalid codes, and they silently break the entire cluster when they happen. Google's documentation calls hreflang one of the trickiest attributes to get right, and the data backs that up — return-tag errors are the single most frequent failure in international SEO audits.
The mistakes I see most often:
- Wrong or invalid codes. Using
en-uk(the country code isgb) orptwhen you meantpt-br. Region without language (hreflang="us") is invalid — language always comes first. - Relative URLs.
/fr/pageinstead ofhttps://example.com/fr/page. Hreflang requires absolute URLs. - Pointing to non-canonical or redirecting URLs. Hreflang must point to the final, indexable, self-canonical version — not a URL that 301s or carries a canonical to somewhere else.
- Conflicting canonical tags. A French page that canonicalizes to the English version tells Google to ignore French. Each version self-canonicalizes. See what is a canonical tag for the full rule.
- Mixing implementation methods. HTML tags on some pages and sitemap entries on others create contradictory mappings.
Catch these before they cost you traffic. A free SEO and GEO audit crawls your pages and flags broken return tags, invalid codes, and canonical conflicts in one pass — far faster than checking pages by hand.
Do You Actually Need Hreflang?
You need hreflang only when you publish substantially the same content in multiple languages or for multiple regions. If your site exists in one language and targets one country, hreflang adds nothing — skip it entirely.
Use the decision flow below to check whether hreflang applies to your situation.
- Multiple language versions?If the same content exists in two or more languages, hreflang likely applies.
- Or multiple regions, same language?US vs UK English or pt-br vs pt-pt also needs hreflang to target the right audience.
- Single language, single region?If you serve one language to one country, skip hreflang — it adds nothing.
- Pick one methodChoose HTML head, HTTP headers, or XML sitemap — never mix methods on the same page.
- Add return tags everywhereEvery page must reference every alternate, including itself, or Google ignores the set.
- Validate and auditConfirm absolute URLs, valid ISO codes, and self-canonicals, then re-audit after launch.
The classic case for hreflang is regional variants of the same language: a US English page and a UK English page with different pricing, spelling, or shipping terms. Without hreflang, Google may show the US page to UK searchers, hurting relevance. Hreflang resolves that. The same applies to Spanish for Spain versus Latin America, or French for France versus Canada.
If you only translate a handful of pages, implement hreflang for those URLs and leave the single-language pages alone. And remember: hreflang manages which version is shown, not whether you rank. You still need solid content, fast pages, and the rest of your technical SEO foundation behind it.