Hreflang tags: syntax, examples, common mistakes and how to check them

The hreflang tag tells Google which version of a page to serve depending on the visitor’s language and country. It is written with an ISO 639-1 language code, optionally followed by an ISO 3166-1 alpha-2 country code. It must be reciprocal and reference itself: as soon as one version is missing, Google ignores the whole group. That is what makes this markup as simple to write as it is easy to break.

What are hreflang tags for in SEO?

Language, country, or both

There are three ways of writing it, and they do not mean the same thing. The code on its own, en, targets all English speakers wherever they are. The language and country pair, en-GB, targets English speakers in the United Kingdom. Country alone does not exist: writing hreflang="ca" does not target Canada, it designates Catalan, which carries that language code. It is the most common mistake on sites organised by market rather than by language.

The choice follows from your catalogue. If the content is identical for all English speakers, a single en is enough and saves you maintaining ten variants. If prices, currency, legal notices or availability change from one country to another, then language and country pairs are justified.

What it does not do

To designate the preferred URL between two near-identical versions, you need the canonical tag, not hreflang.

The tag is not a ranking factor. It does not push a page up; it swaps one page for another in the results, at an equivalent position. Nor does it replace translation: two identical pages in two different languages remain two weak pages. And contrary to a widespread belief, it blocks nothing: it is neither an indexing directive nor protection against duplicate content, only a matching signal.

Hreflang tag syntax: examples for the three possible locations

In the head of the page

This is the most common and most readable method. Each version lists every version, itself included.

<link rel="alternate" hreflang="en-US" href="https://example.com/us/page/">
<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page/">
<link rel="alternate" hreflang="fr-CA" href="https://example.ca/fr/page/">
<link rel="alternate" hreflang="x-default" href="https://example.com/page/">

This block must be strictly identical on all four pages. That redundancy is what makes the markup machine-verifiable, and tedious to maintain by hand.

In the HTTP header, for files

An HTML page has a head; a PDF does not. For files, the declaration therefore goes through the server’s response header, with the same reciprocity logic.

Link: <https://example.com/guide.pdf>; rel="alternate"; hreflang="en-US",
      <https://example.fr/guide.pdf>; rel="alternate"; hreflang="fr-FR"

In the XML sitemap, for large sites

Beyond a few hundred multilingual pages, declaring in the head becomes unmanageable: every new language means editing every existing page. The sitemap centralises everything in one place, which simplifies maintenance and lightens the HTML. It is the method I recommend as soon as a site goes beyond three markets.

Hreflang errors: the six traps that come up all the time

• Missing return links. Page A references page B, but B does not reference A. Google then ignores the declaration, often silently.
• Forgotten self-reference. Each page must reference itself. It is counter-intuitive, and it is mandatory.
• Made-up codes. en-GB is valid, and so is en-gb since case is ignored, but en-UK, uk for the United Kingdom or eu for Europe are not recognised codes.
• Pointing to a dead or non-indexable page. An hreflang that points to a 404, a redirect or a noindex page breaks the whole group.
• Conflict with the canonical tag. If the German version declares itself canonical to the English version, you are saying two opposite things. The canonical wins, and your hreflang is useless.
• x-default missing when it is needed. It designates the version to serve when none matches. Without it, a visitor from Japan lands on a page picked at random from your versions.

How to check your hreflang tags before deploying them

Paste your block into the tool below: it checks for the self-reference, the validity of language and country codes, duplicate codes, duplicate URLs and the presence of an x-default. Nothing leaves your browser. Once the block is validated, the site’s hreflang tag generator produces the head and sitemap versions from your list of URLs.

For checking in real conditions, Search Console remains the reference: it reports tags without return links and unknown codes, on the pages it has actually crawled. A crawler such as Screaming Frog does the same job before going live, across the whole site.

Hreflang on WordPress: what actually works

WordPress does not handle multilingual content natively, and no general SEO plugin produces correct hreflang markup on its own: they do not know which pages correspond to each other across languages. That mapping is the job of multilingual plugins, which store the link between the original page and its translation, then output the markup automatically.

The three families are technically equivalent, and are chosen mostly according to how you work: in-house translation with two or three languages, full editorial management with translation workflows, or machine translation served from a subdomain. In every case, check the real output after installation rather than the promise on the product page, and be wary of setups that produce one version per country without the content changing by a single byte.

Hreflang codes to know, and the ones that do not exist

Value	What it targets	Valid
en	All English speakers	Yes
en-GB, en-US, en-CA, en-AU	English speakers in a given country	Yes
fr-FR, es-ES, es-MX, pt-BR	Language and market	Yes
x-default	Default version, when nothing matches	Yes
uk	Meant to target the United Kingdom, designates Ukrainian	No
eu, latam, en-EU	Made-up geographic regions	No

One last useful pointer: the country code is for geographic targeting, not for the language spoken there. en-CA designates English speakers in Canada, fr-CA French speakers in the same country, and the two can coexist without getting in each other’s way.