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. For a deeper dive into strategy and advanced scenarios, see our pillar hreflang guide.

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 tag format is defined in RFC 5646. See the full hreflang language codes reference for common codes and gotchas.

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. See our hreflang HTML examples for copy-paste templates.

<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. For more on how sitemaps and hreflang interact, see this hreflang sitemaps guide.

<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.

Try Hreflang Generator

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. If your content is the same across regions, read do you need hreflang for a single language for guidance.

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. See hreflang and canonical tags for the full rules.

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.

For a detailed breakdown of each mistake and how to fix it, read 7 common hreflang mistakes.

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. See our hreflang checker tools comparison for tooling options, and follow the hreflang best practices checklist to keep your implementation clean.

Related Articles

References

Generate perfect hreflang tags

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

Try Hreflang Generator