What is hreflang? A complete, plain-English guide

Updated Published 11 min read

In short

hreflang is an HTML annotation that tells search engines which language and region a page is intended for, so they can serve the right version to the right user. It is declared as a link element in the page head, an HTTP header, or a sitemap entry. Annotations must be reciprocal: every version links to every other, including itself.

Key points

  • hreflang tells search engines which language and region each version of a page targets; it does not translate anything or change what a visitor sees.
  • Annotations must be reciprocal — if page A lists page B, page B must list page A, or Google may ignore the annotation entirely.
  • Every page in a set must also reference itself, and the set should include an x-default entry for users matching no specific version.
  • hreflang is a signal, not a directive: Google treats it as a strong hint rather than a guarantee of which version it will show.
  • You can declare hreflang in the HTML head, in HTTP headers, or in an XML sitemap — pick exactly one method per page.

hreflang is an HTML annotation that tells search engines which language and region a page is meant for, so they can show the right version to the right user. If your site exists in several languages, hreflang is what stops Google from showing a French visitor your English page — or treating your translated pages as competing duplicates.

What does hreflang actually do?

hreflang links the language versions of a page together and labels each one's intended audience. It does not translate anything, it does not redirect anyone, and it does not change what a visitor sees when they click a link. Its entire job is to describe a relationship between URLs so a search engine can pick the most appropriate one for a given searcher.

Google describes hreflang as a way to tell it about localized versions of a page, and is explicit that these annotations are treated as a signal rather than a directive — a strong hint about which version to surface, not a binding instruction (Google Search Central). That distinction matters when you are debugging: seeing the "wrong" version in results does not automatically mean your markup is broken.

Why does hreflang matter?

Without hreflang, a search engine has to guess which version of a page to rank and show. That produces two distinct problems.

The first is a user-experience problem: a Spanish searcher lands on your English page, doesn't find what they expected, and leaves. The page may have been perfectly relevant — in the wrong language.

The second is a consolidation problem: several near-identical pages, differing mainly by language, compete for the same query. Duplicate handling may pick one version and effectively suppress the rest. hreflang resolves both by explicitly declaring that these pages are alternates of one another, each aimed at a different audience, rather than redundant copies.

What does an hreflang tag look like?

The most common form is a <link> element in the page <head>:

<link rel="alternate" hreflang="de" href="https://example.com/de/" />

It has three parts:

  • rel="alternate" — declares that the target is an alternate version of this page.
  • hreflang="de" — the language, optionally followed by a region.
  • href — the fully-qualified URL of that version, including the protocol.

A complete set for a page available in English, German and French looks like this, and appears identically on all three pages:

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

You can generate a correct set with the free hreflang generator.

What language codes should you use?

The value is a language code, optionally followed by a hyphen and a region code. Google specifies the language in ISO 639-1 format and the optional region in ISO 3166-1 Alpha 2 format; these are the same building blocks used by the broader language-tag standard defined in RFC 5646 (BCP 47).

Valid examples: en, de, en-GB, pt-BR, zh-Hant.

Two rules save most of the pain here:

  • Use a bare language code unless you genuinely have different content per region. en covers every English speaker. Only reach for en-GB and en-US if the pages actually differ — different pricing, different spelling, different legal terms.
  • A region code alone is never valid. hreflang="us" does not mean "United States"; us is not a language. Use en-US.

The full language-code reference lists the valid combinations.

What is x-default?

x-default is a reserved value that tells search engines which page to show users who don't match any of your specific versions. A Japanese speaker visiting a site available only in English, German and French matches none of them — x-default decides what they get.

<link rel="alternate" hreflang="x-default" href="https://example.com/" />

Point it at whichever page best serves an unmatched visitor: usually your main-language homepage, or a language-selector page if you have one. It is optional, but on a genuinely multilingual site there is rarely a good reason to omit it.

The reciprocity rule (the one everybody breaks)

hreflang only works if the annotations are reciprocal. If page A declares page B as its German alternate, then page B must declare page A as its English alternate. Google states plainly that annotations without return links may be ignored — not partially honoured, but disregarded.

In practice this means every language version of a page carries the same complete block of hreflang tags, including a link to itself. The self-reference is not optional decoration; it is part of what makes the set valid.

This single rule accounts for the majority of "hreflang isn't working" reports. A page gets added in one language and not linked from the others; a URL changes on one version and not the rest; a redirect quietly breaks a return link. Verify a live page with the free hreflang checker, then open one of the URLs it reports and confirm the annotation points back.

Where can hreflang be declared?

Google supports three methods, and you should use exactly one per page:

  • HTML <head> — the most common approach and what most WordPress plugins emit. Simplest to inspect and debug.
  • HTTP headers — the right choice for non-HTML resources such as PDFs, where there is no head to put a link element in.
  • XML sitemap — annotations expressed as <xhtml:link> alternates. Useful on large sites because it keeps the markup out of every page and centralises maintenance in one file.

Mixing methods for the same page invites contradictory signals. Pick one and be consistent.

How does hreflang relate to canonical tags?

These two are frequently confused, and getting the relationship wrong is the second most common failure after reciprocity.

A canonical tag says "this is the preferred URL for this content." An hreflang annotation says "this is the equivalent page for a different audience." They operate at different levels, and they must agree.

The rule: each language version should have a self-referencing canonical. Your German page's canonical points at the German page. If you instead point every translation's canonical at the English original, you are telling Google the translations are duplicates that should be consolidated away — which directly contradicts the hreflang annotations saying they are distinct alternates. Google's guidance on specifying a canonical URL covers the mechanics.

How does hreflang relate to the lang attribute?

The lang attribute on the <html> element declares the language of the current document — it is consumed by browsers, screen readers, and translation tools. hreflang describes relationships between documents, for search engines.

They serve different consumers and you need both. A German page should carry <html lang="de"> and appear in the hreflang set. For right-to-left languages, add dir="rtl" alongside the lang attribute.

Common hreflang mistakes

  • Non-reciprocal annotations. The number-one error. Every version must link to every other version.
  • Missing self-reference. Each page must include itself in its own hreflang set.
  • Invalid codes. en-UK instead of en-GB; a region code used on its own; a made-up locale.
  • Relative or non-canonical URLs. Use absolute URLs including the protocol, and point at the indexable canonical version — not a URL that redirects.
  • Pointing at noindexed or redirecting pages. An annotation targeting a page that cannot be indexed wastes the signal.
  • Conflicting canonicals. Cross-language canonicals that collapse your translations into the source page.
  • Mixing declaration methods. Head links on some pages, sitemap annotations on others, for the same URLs.
  • Forgetting new pages. Every page added in one language needs adding to the set on all the others.

Do you have to maintain hreflang by hand?

No — and on a real site you shouldn't. The maintenance burden scales with pages multiplied by languages: fifty pages in four languages is two hundred annotation blocks, each of which must stay reciprocal as content changes. That is precisely the kind of bookkeeping that decays silently.

A translation plugin such as Gloty generates reciprocal hreflang with x-default, per-language self-referencing canonicals, and translated meta automatically for every page, so the set stays correct as the site grows. For the WordPress-specific setup steps, see how to add hreflang in WordPress.

Sources

Technical claims in this guide are drawn from the primary documentation and specifications below, each confirmed live on the date shown.

  1. Tell Google about localized versions of your page — Google Search Central. Accessed .
  2. Managing multi-regional and multilingual sites — Google Search Central. Accessed .
  3. How to specify a canonical URL with rel="canonical" and other methods — Google Search Central. Accessed .
  4. RFC 5646 — Tags for Identifying Languages (BCP 47) — IETF. Accessed .
  5. Sitemaps XML format — sitemaps.org. Accessed .

FAQ

Is hreflang a ranking factor?
Not directly — correct hreflang does not boost rankings. It ensures the appropriate language or regional version is shown to each user and prevents translated pages from being treated as competing duplicates, which protects the rankings you already have rather than adding new ones.
Do I need hreflang if I only have one language?
No. hreflang is only needed when equivalent content exists in multiple languages or regional variants. A single-language site has nothing to annotate.
What's the difference between hreflang and the lang attribute?
The html lang attribute declares the language of the current page for browsers, screen readers and translation tools. hreflang links the different language versions of a page together for search engines. They serve different consumers, and a correct multilingual page has both.
What happens if hreflang is not reciprocal?
Google may ignore the annotations entirely. Reciprocity is a validity requirement, not a best practice — if page A lists page B as an alternate but page B does not list page A in return, the whole set can be disregarded rather than partially honoured.
Can hreflang and canonical tags conflict?
Yes, and it is a common failure. Each language version needs a self-referencing canonical. Pointing every translation's canonical at the source-language page tells search engines the translations are duplicates to consolidate, contradicting the hreflang annotations that declare them distinct alternates.
Where should hreflang go — head, HTTP header, or sitemap?
Any of the three is valid, but use only one method per page. HTML head links are the most common and easiest to debug, HTTP headers exist for non-HTML files such as PDFs, and XML sitemap annotations suit large sites by centralising maintenance in one file.

Gloty makes WordPress multilingual automatically — AI translation, hreflang, and clean URLs, stored in your own database.

Try Gloty free
Go multilingual free
Open source · your data stays yours
Start free