How to Add hreflang Tags to Your Website (Step-by-Step)

hreflang tags tell Google which language or regional version of a page to show each visitor. Get them right and your translated pages rank in the right markets. Get them wrong — which most sites do — and Google quietly ignores the whole thing. This guide covers the three ways to add hreflang, the exact syntax, the handful of mistakes that break almost every implementation, and how to confirm yours actually works. No deep coding required.

You translated your website. The pages are live. So why is the English version still showing up for searchers in France, and why isn't your Spanish page ranking in Mexico?

Nine times out of ten, the answer is hreflang — either missing, or broken in a way that makes search engines throw it out. Google's own John Mueller has called hreflang "one of the most complex aspects of SEO (if not the most complex one)" — it feels as easy as a meta tag but gets hard fast.

The good news: you don't need to be a developer to get it right. You just need to understand what hreflang is doing, avoid the few mistakes that sink most setups, and pick an implementation method that fits your site. Let's go.

What hreflang Tags Actually Do

An hreflang tag is a small annotation that tells search engines: "This page is the language/region version of this content — and here's where the other versions live." Google introduced it back in 2011, and it's still fully supported in Google's documentation as of late 2025.

It solves three problems at once:

1. Serving the right version to the right person. When someone in France searches, hreflang helps Google show them yoursite.com/fr/ instead of your English original. The textbook example: search "Adidas official website" and you get adidas.com in the US but adidas.fr in France.
2. Stopping duplicate-content confusion. Two pages that say the same thing in English-US and English-UK — or English and Spanish — could look like duplicates. hreflang signals these are intentional variations, not copies, so your ranking signals don't get split.
3. Targeting multiple markets cleanly. One body of content can serve many audiences: fr-be (French for Belgium), nl-be (Dutch for Belgium), de-be (German for Belgium), and so on.

One thing hreflang does not do: it doesn't tell Google what language a page is written in. Google detects that on its own. hreflang only describes the relationships between your versions and who each one is for.

It's also worth setting expectations early — hreflang is a hint, not a command. Mueller reiterated in 2025 that it doesn't guarantee indexing, and that near-identical variants (like fr-fr and fr-be) often get consolidated to a single canonical URL in reporting. So hreflang won't magically multiply your traffic. Its job is correct targeting — showing the right version to the right user.

Why hreflang Is Worth the Effort

If hreflang is just a hint, why bother? Because the alternative is letting Google guess — and it guesses wrong constantly.

Without hreflang, you'll see your English page outranking your translated page in its own home market, the wrong regional version surfacing, or near-duplicate pages cannibalizing each other. And the stakes are real: according to CSA Research's widely-cited "Can't Read, Won't Buy" study of 8,709 consumers across 29 countries, 76% of online shoppers prefer to buy products with information in their native language, and 40% will never buy from sites in another language. If your translated page exists but never reaches its audience, that investment is wasted.

The catch is that hreflang is shockingly easy to get wrong. An analysis by SEMrush of 20,000 multilingual websites (reported by Search Engine Journal) found that roughly 75% had at least one hreflang implementation error. When three-quarters of sites trip over the same wires, the wiring deserves attention.

The silver lining, straight from Google: if your hreflang is broken, Google generally just ignores the signal rather than penalizing you. So there's no downside to fixing it — only upside.

The Three Ways to Add hreflang

Google supports three implementation methods, and here's the key thing most guides bury: they're equivalent, and you should only use one. Google explicitly says there's no SEO benefit to combining them, and that managing more than one is "much harder" and a common source of conflicts.

For most site owners, the choice comes down to: HTML head tags (usually output by a plugin or tool) or an auto-generated sitemap. You almost never need to touch HTTP headers unless you're serving translated PDFs. And critically — whichever you pick, don't hand-maintain it across dozens of pages. That's where errors creep in. Let a plugin, platform feature, or translation tool generate them.

hreflang Syntax, Made Simple

Here's a single hreflang annotation, the kind that goes in your page <head>:

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

Three parts:

• rel="alternate" — "this points to an alternate version of this page."
• hreflang="fr" — the language (and optionally the region).
• href — the full, absolute URL (always include https:// — never a relative path like /fr/page).

Language and region codes

• Language uses ISO 639-1 codes: en, fr, de, es, ja.
• Region is optional and uses ISO 3166-1 Alpha-2 codes, joined with a hyphen: en-GB, pt-BR, fr-CA. Use a hyphen, never an underscore.

Two rules that trip people up constantly:

1. You can use a language alone (de = German for anyone), but you can never use a region alone. hreflang="be" does not mean Belgium — be is the code for the Belarusian language. To target Belgium you must lead with a language: fr-be, nl-be, or de-be.
2. Some "obvious" codes are wrong. The UK's region code is gb, not uk. Codes like uk, eu, and un are invalid and get ignored.

The x-default value

hreflang="x-default" sets the fallback page for visitors whose language or region doesn't match any of your versions — think of it as your "everyone else" option:

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

It's not strictly required, but it's strongly recommended, especially for homepages and language-selector pages.

A complete example

Here's what a full set looks like for a site with US, UK, generic English, and German versions. This exact same block goes in the <head> of every page listed — including each page referencing itself:

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

That "every page references itself" detail isn't optional — and it's exactly where most implementations fall apart.

The 7 Mistakes That Quietly Break hreflang

If you read nothing else in this guide, read this section. These are the errors behind that 75% failure rate.

1. Missing return tags (the #1 killer). hreflang must be bidirectional. If page A points to page B, page B must point back to page A — and every page must reference itself. If the links aren't reciprocal, Google throws them out entirely. This is by design, so other sites can't hijack your tags. At scale it's brutal: 10 languages × 10 pages = 100 perfectly synced annotations. The fix is to generate them from a single source of truth, never by hand.
2. Wrong language or region codes. en-uk instead of en-gb, or invented codes. Google ignores anything it doesn't recognize. Always check against ISO 639-1 (language) and ISO 3166-1 Alpha-2 (region).
3. Using a region code on its own. As above — you can't target a country without naming a language. hreflang="us" is meaningless.
4. Missing x-default. Not fatal, but you're leaving your "everyone else" visitors to chance.
5. Relative URLs instead of absolute ones. Always https://example.com/fr/page, never /fr/page.
6. Canonical conflicts (the silent one). If a page's canonical tag points to a different URL, Google discards that page's hreflang completely — and because hreflang is reciprocal, that can break the entire cluster. The rule: each translated page needs a self-referencing canonical (your French page canonicals to itself, not to the English original). Never cross-canonicalize language versions.
7. Pointing at dead ends. Every hreflang URL should return a 200 status, be indexable, and not be blocked by robots.txt. Don't point hreflang at redirected, noindexed, or broken pages.

Notice how many of these are consistency problems — reciprocal links, matching canonicals, synced codes across every page. Humans are bad at maintaining that kind of consistency across a growing site. Machines are good at it. Keep that in mind.

How to Add hreflang on Your Platform

The practical question: how do you actually do this on the site you have? Here's the path for the most common setups.

WordPress

WordPress doesn't output hreflang on its own, and neither does Yoast SEO by itself (Yoast has no multilingual features). You need a translation or multilingual plugin:

• WPML (premium) or Polylang (free) are the two standards. Once you create and link your translations, they generate reciprocal hreflang automatically — WPML even adds it to your XML sitemap and integrates with Yoast.
• Steps: install and activate the plugin → set up your languages → translate and link your content → the plugin outputs hreflang automatically → confirm with View Source.

If you'd rather not manage a heavy translation plugin (WPML and Polylang change how your whole content model works), a reverse-proxy tool handles hreflang without touching your WordPress install at all — more on that below, and there's a dedicated WordPress setup path if you go that route.

Shopify

Shopify Markets generates hreflang automatically. Per Shopify's docs, hreflang and meta tags are created for every international domain or subfolder you set up, and they update automatically when you change market or language settings. Use subfolders (yourstore.com/fr/) rather than separate domains so you keep your domain authority — here's why subdirectories usually win.

One warning: if you also add hreflang manually via your theme or an SEO app, you can create conflicts with Shopify's automatic tags. Audit what Markets is already doing before you add anything.

Webflow

Webflow Localization auto-generates page-level hreflang in the <head>, includes it in the sitemap, sets the lang attribute per locale, uses subdirectory URLs, and even handles right-to-left layout for Arabic and Hebrew. Your primary locale becomes the x-default. Leave auto-generation on unless you're running a custom CDN. (Note: if you build a multilingual Webflow site manually without Localization, Webflow does not add hreflang — you'd be back to custom code.)

Any platform: the reverse-proxy route

If you're on a framework like Next.js, Nuxt, Framer, or anything custom — or you just don't want to install and maintain a translation plugin — a reverse-proxy translation tool sits in front of your site, translates the rendered HTML, and injects all the SEO tags before search engines see the page. It works on any platform without plugins or code changes. That's the category Verbi falls into, which brings us to the easiest option.

The No-Code Way: Let It Happen Automatically

Step back and look at the mistake list again. Reciprocal tags. Self-referencing canonicals. Correct ISO codes. x-default. Absolute URLs. Synced sitemaps. Every single one is a consistency problem — exactly the kind of thing that's tedious and error-prone for a person to maintain, and trivial for software to get right every time.

That's the whole argument for automating hreflang rather than hand-coding it. Verbi is built on this model: it works as a Cloudflare reverse proxy, so you point your domain to it with a couple of DNS records (no plugin, no rebuild) and translations get served from Cloudflare's edge on any platform.

Because Verbi translates at the server level, Google crawls fully translated HTML — not JavaScript that search engines can't reliably read, which is the trap with free translate-widget scripts. And on the hreflang side specifically, it handles the entire checklist automatically:

• Reciprocal hreflang injected on both your original and translated pages — solving mistake #1 by construction
• x-default pointing to your original
• Correct BCP 47 codes like pt-BR and zh-Hans
• Subdirectory URLs (/fr, /es, /de) — Google's recommended structure
• A dedicated hreflang sitemap with per-URL entries, referenced in your robots.txt
• Self-referencing canonicals pointing each page to its own language version — avoiding the canonical conflict in mistake #6
• Content-Language headers and correct html lang / dir="rtl" for languages like Arabic

And because translation and tags stay in sync automatically, your hreflang clusters don't drift out of alignment as you update your site — which is the slow-motion way most manual implementations eventually break. Translation runs on DeepL, which produces noticeably more natural output for European languages. Plans start at $15/month with a 14-day free trial.

The point isn't that you must use a tool — plenty of WordPress, Shopify, and Webflow setups handle hreflang fine through their native features. The point is that hreflang rewards automation, whatever form it takes, because the failure mode is always manual drift.

How to Test Your hreflang

Don't assume it works — verify it. Here's how, in order of effort.

Quick spot-check (free, 30 seconds): Open any translated page → View Page Source → search for "hreflang." Confirm each version appears with absolute URLs, the page references itself, and x-default is present.

Single-page validators (free):

• Merkle's hreflang Testing Tool — recommended in Google's own docs; checks one live page's tags in HTML, headers, or sitemaps. Great for verifying a fix.
• Aleyda Solis's hreflang Generator — also recommended by Google; produces correct tags from your language/region inputs so you start clean.

Site-wide audits:

• Screaming Frog SEO Spider — the most thorough; its hreflang tab flags missing return links, bad codes, canonical conflicts, and non-reciprocal tags across your whole site.
• Ahrefs Site Audit — flags nine hreflang issues with a visual cluster view, and Ahrefs' guide is one of the clearest references out there.

One thing that's changed: Google Search Console used to have a dedicated International Targeting report for hreflang errors, but Google removed it after September 2022 and never replaced it. hreflang itself is still fully supported — you just won't find a hreflang error list inside GSC anymore. Use URL Inspection to confirm your regional pages are indexed, and lean on the third-party tools above for error checking.

The Bottom Line

hreflang isn't complicated to understand — it's complicated to maintain. The concept fits in a sentence: tell search engines where each language version lives, make every reference reciprocal, and use correct codes. The difficulty is keeping that perfectly consistent across every page as your site grows.

So the smart approach depends on your situation:

• Small site, like control? Hand-add the HTML head tags using Aleyda Solis's generator, then validate every page with Merkle's tester.
• On WordPress, Shopify, or Webflow? Use the native multilingual features (WPML/Polylang, Markets, Localization) and let them generate hreflang — then audit with Screaming Frog to be sure.
• Want zero code, zero platform lock-in, and translation handled too? A reverse-proxy tool like Verbi generates reciprocal hreflang, self-referencing canonicals, x-default, correct codes, and synced sitemaps automatically — eliminating the manual drift that breaks most setups.

Whatever you choose: implement one method, make it reciprocal, validate it, and re-check after any structural change. Do that, and your translated pages will finally reach the people you translated them for.

Frequently Asked Questions

Do I need hreflang if I only have one language?

No. hreflang only matters when you have the same or similar content in multiple languages or regional variants. A single-language site doesn't need it.

Where do hreflang tags go?

You can place them in three locations, and you should pick only one: HTML <link> tags in the page <head>, entries in your XML sitemap, or HTTP headers (used only for non-HTML files like PDFs). For most sites, head tags or the sitemap — usually generated by a plugin or tool — are the practical choice.

What is the x-default hreflang value?

x-default specifies the fallback page for visitors whose language or region doesn't match any of your defined versions. It's commonly used on homepages and language-selector pages, and while not strictly required, it's strongly recommended.

Why is Google ignoring my hreflang tags?

The most common reasons are missing return tags (page A references page B but B doesn't reference A), invalid language or region codes, missing self-references, or a canonical tag that points to a different URL than the hreflang. Run the page through Merkle's hreflang tester or Screaming Frog to pinpoint which one.

Is hreflang a ranking factor?

Not directly. hreflang is a targeting signal, not a ranking boost — it helps Google serve the right version of a page to the right user, but it won't push a page higher on its own. Don't expect a traffic spike from adding it; expect the right pages to start showing in the right markets.

Can I add hreflang without coding?

Yes. WordPress plugins (WPML, Polylang), Shopify Markets, and Webflow Localization all generate hreflang automatically once configured. Reverse-proxy translation tools like Verbi go further — you add a couple of DNS records and hreflang, canonicals, sitemaps, and meta tags are generated and kept in sync automatically, on any platform, with no code.

Does the International Targeting report still exist in Google Search Console?

No. Google deprecated and removed the International Targeting report after September 2022, with no direct replacement. hreflang remains fully supported — you just validate it now with third-party tools like Merkle, Screaming Frog, or Ahrefs instead.