SEO

Hreflang Tags Explained: Implement and Generate Them Right

By Yana Markova · November 12, 2026 · 8 min read

If your site has the same content in more than one language or for more than one country, hreflang tells Google which version belongs to which audience. Get it right and a visitor in Spain sees your Spanish page. Get it wrong and Google may show the wrong version or ignore your annotations altogether.

This guide explains how hreflang works, the rules to follow, and a template you can use as your own “generator.”

What hreflang does (and does not do)

Hreflang is a signal that says, “these pages are equivalent versions of each other, each for a different language or region.” Google uses it to swap the right version into search results for the right user.

It does not boost rankings on its own, it does not translate anything, and it is a hint, not a command. It is most useful when you have near-duplicate pages, such as English pages for the US and the UK, or the same page translated.

The syntax

A language code uses ISO 639-1 (en, es, fr). A region can be added with an ISO 3166-1 Alpha 2 country code (en-us, en-gb, es-mx). Some rules to remember:

  • You can use a language alone (es) or language plus region (es-mx).
  • You cannot use a region alone. us or gb by itself is invalid.
  • The special value x-default marks the fallback page for users who match none of your versions.

Three ways to implement hreflang

You only need to use one of these methods for a given set of pages. Pick the one that fits your setup.

1. HTML link elements in the head

Add one link tag per version, on every version of the page:

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

This is the easiest option for smaller sites.

2. HTTP headers

For non-HTML files such as PDFs, you can send hreflang in the HTTP response header. This is less common and needs server configuration.

3. XML sitemap

For large sites, list the alternates inside your sitemap so you are not adding dozens of tags to every page. Each URL entry includes xhtml:link elements for all of its alternates, including itself.

The rules that cause most errors

  1. Return links are required. If page A points to page B, page B must point back to page A. Missing return links are among the most common hreflang problems and cause annotations to be ignored.
  2. Include a self-reference. Each page should list itself in its own set of alternates.
  3. Use absolute, fully qualified URLs that match the canonical version of each page.
  4. Point to indexable pages. Hreflang URLs that redirect, return errors, or are blocked from crawling will not work.
  5. Keep canonicals consistent. Each language page should usually canonicalize to itself. If every version canonicalizes to one page, you are telling Google to ignore the others.
  6. One x-default per group. Google describes x-default as designed for language selector pages but usable on any page. Specify only one per set of equivalent content.
  7. Use valid codes. Typos such as en-uk (the correct region code is gb) are a classic mistake.

Generate your hreflang set

The fastest route is our free hreflang tag generator: enter your URLs and language codes and it builds the full set of tags. You can also do it by hand, and the process is the same either way:

  1. List every page that has equivalents in other languages or regions.
  2. For each group, write down the full URL, the language code, and the optional region code.
  3. Choose your x-default (often a global page or language selector).
  4. Create the same full set of tags for every page in the group. This is what satisfies the return link rule.
  5. Paste them into each page’s head, or into your sitemap.

For larger sites, a spreadsheet with one row per URL and one column per language lets you build all the tags with a simple formula. If you want to automate the repetitive parts, Claude Code can generate and validate the markup from a spreadsheet, and you review the output before deploying.

Test and monitor

  • Spot check a few pages by viewing the page source or using the URL Inspection tool in Google Search Console.
  • Crawl the site with an SEO crawler and look for missing return links, invalid codes, and non-indexable targets.
  • Watch Search Console after launch for indexing changes in each language folder.
  • Check Bing separately. Bing relies on other language signals, so confirm your setup against Bing’s guidance if that traffic matters to you.

When you do not need hreflang

  • Your site is in one language and targets one market.
  • Translated pages are substantially different content, not equivalents.
  • You are using separate country sites with distinct content and no overlap.

In those cases, focus on the basics: clear site structure, fast pages, and solid content. Our international SEO strategy guide covers the bigger picture, and our guide on technical SEO for infinite scroll and pagination covers another area where crawlable URLs matter.

A worked example

Imagine a pricing page that exists in US English, UK English, and Spanish. Each of the three pages must contain the same four lines in its head:

  1. en-us pointing to the US page
  2. en-gb pointing to the UK page
  3. es pointing to the Spanish page
  4. x-default pointing to your default or selector page

The US page lists itself and the other two; the UK page does the same; the Spanish page does the same. That gives you return links and self-references without extra thought. If you add a French page later, you must add the French line to all three existing pages as well as create the French page’s own set. This is the step people forget, and it is why large sites generate the tags from a spreadsheet or a template instead of by hand.

Free tools and related reading

Free tools on this site:

Related guides:

Launching in new markets and want the technical setup done right? Our SEO and organic growth service covers international SEO audits and implementation. Contact us to talk it through.

Frequently asked questions

Is hreflang a ranking factor?

No. It helps Google show the right regional or language version to the right user, but it does not add ranking strength.

Do I need hreflang if I use different languages on different domains?

It still applies. Hreflang works across domains as long as the return links and URLs are correct.

What should x-default point to?

Usually a page that works for everyone else: a global homepage, a language selector, or your default language version.

Can I mix methods?

Avoid it. Using several methods for the same pages makes conflicts harder to find. Choose HTML tags, headers, or a sitemap and stay consistent.