H
Hreflang Generator

Hreflang Tags: The Complete SEO Guide

Everything you need to know about hreflang tags for SEO: syntax, implementation methods, common pitfalls, and best practices for multilingual sites.

Hreflang tags are the mechanism search engines use to understand which version of your content is meant for which audience. If you run a multilingual or multi-regional site, getting hreflang right is one of the highest-leverage technical SEO tasks you can do.

This guide covers everything: syntax, all three implementation methods, self-referencing, x-default, and validation.

Tag anatomy

A single hreflang tag looks like this:

<link rel="alternate" hreflang="en-us" href="https://example.com/en-us/pricing/" />

Breaking it down:

  • rel="alternate" -- signals this is an alternate version of the current page
  • hreflang="en-us" -- specifies the language (en) and optional region (us)
  • href -- the absolute URL of that language/region variant

Language codes follow ISO 639-1 (two-letter codes like en, fr, de). Region codes follow ISO 3166-1 alpha-2 (US, GB, DE). The region portion is case-insensitive -- en-US and en-us are both valid.

The full hreflang set

Every page in a hreflang group must list all variants in the group -- including itself. If you have three language versions of a page, each page needs three link elements:

<!-- On your /en/ page -->
<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/" />

<!-- On your /fr/ page -- same three links -->
<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<link rel="alternate" hreflang="de" href="https://example.com/de/" />

The self-referencing tag (linking to the page itself) is required. Missing it is one of the most common hreflang errors.

Three implementation methods

1. HTML <head> (most common)

Place your hreflang link elements inside the <head> of every affected page. This is the standard approach for most websites.

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

2. HTTP headers (for non-HTML files)

For PDFs, Word documents, or other non-HTML resources, you can't add <link> elements. Use HTTP response headers instead:

Link: <https://example.com/en/doc.pdf>; rel="alternate"; hreflang="en",
      <https://example.com/es/doc.pdf>; rel="alternate"; hreflang="es"

3. XML sitemap (for large sites)

Large sites with thousands of pages often manage hreflang via the XML sitemap to avoid editing each page's HTML. This uses the xhtml:link element inside each <url> block.

<url>
  <loc>https://example.com/en/</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/" />
  <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
</url>

Generate hreflang tags for your entire site

Paste your URLs and get production-ready hreflang markup for all three implementation methods.

x-default: the fallback tag

x-default is a special hreflang value for when none of your other language/region tags match the user. It's typically used for:

  • A language selection page
  • Your default language when no better match exists
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

It's recommended but not required. If you have a global fallback page, add it.

Language targeting vs. region targeting

You can be as specific or general as you need to be:

  • hreflang="es" -- targets all Spanish speakers, regardless of country
  • hreflang="es-es" -- targets Spanish speakers in Spain specifically
  • hreflang="es-mx" -- targets Spanish speakers in Mexico specifically

Use region targeting when your content genuinely differs by country -- different pricing, different legal requirements, different product availability. Don't use region targeting just to create more pages.

Hreflang and canonical tags

Each page's canonical tag should point to itself, not to a "master" language version. If your French page has canonical pointing to your English page, hreflang can't work properly -- Google sees conflicting signals.

The rule: canonical handles duplicate consolidation within the same language. hreflang handles language/region variation across pages.

Common mistakes

Missing return links

Every page in a hreflang set must link to every other page, and every other page must link back. Broken reciprocal links cause Google to ignore the whole cluster.

Missing self-referencing tags

Each page must include itself in its own hreflang set. This is required, not optional.

Wrong language codes

Using uk instead of en-gb, or sp instead of es. Stick to ISO 639-1 and ISO 3166-1 alpha-2.

Canonical pointing to another language

Setting all language variants to canonical the English version tells Google to ignore your hreflang entirely.

Relative URLs

Hreflang href values must be absolute URLs. Relative paths are not supported.

Validation

After implementing hreflang, validate it. Check for:

  • Self-referencing tags on every page
  • Reciprocal links (every page links back to every other)
  • Valid language and region codes
  • Absolute URLs throughout
  • Canonical tags pointing to self, not cross-language

Most hreflang problems are invisible without an audit -- Google will silently ignore malformed tags rather than surfacing an error.

Related Articles

Part of Boring Tools -- boring tools for boring jobs.

Generate perfect hreflang tags

Create and validate hreflang markup for your multilingual site. Free.