International Hreflang: How to Implement It Correctly

Hreflang is an annotation that tells search engines your pages are localized versions of the same content, so the right version reaches the right user. You add it with link tags in the head, HTTP headers or an XML sitemap. Every page must list itself and all of its alternates, every link must be returned by the page it points to, and every code must be valid. Get those three things right and most international hreflang problems disappear.

This guide covers what hreflang does and does not do, how to build the values, which method to pick, how it interacts with canonicals and redirects, and how to check your work before and after launch.

TL;DR

• Hreflang helps Google choose the best localized URL for a user. It is not a ranking boost for a country.
• Use language codes (ISO 639-1), optionally paired with region codes (ISO 3166-1 Alpha 2), and fully qualified URLs including the protocol.
• Pick one method (HTML, HTTP headers or XML sitemap) and use it consistently across the site.
• Each page lists itself and every alternate, and the links must be reciprocal. Add x-default as the fallback.
• Keep canonicals self-referencing and avoid automatic IP-based redirects, which hide regional versions from crawlers.

Table of Contents

• What hreflang does, and what it does not
• Build the values: language, region and URL
• Choose one implementation method
• Reciprocal, self-referencing and x-default
• Canonicals, redirects and crawlability
• A rollout checklist
• Common mistakes and how to fix them
• Our perspective
• Where to get help
• FAQ
• Sources

What hreflang does, and what it does not

Hreflang is a technical attribute that signals to search engines that several pages are localized variations of the same content. It exists for sites serving audiences across different countries or languages, so users are directed to the most relevant version. Google’s documentation on localized versions is the reference for the syntax and rules.

The common misunderstanding is that hreflang boosts rankings in a target country. Google Search Central community guidance describes it as not a geotargeting ranking signal. Its job is URL selection: when your US page and your UK page are both candidates for a query, hreflang helps Google show the one that fits the searcher.

That framing changes how you prioritize the work:

• If your pages are genuinely different (different languages, currencies, shipping, legal text), hreflang is worth the effort.
• If two regional pages are identical English copy with only a flag changed, hreflang will not make either rank better. Fix the content first.
• If you have a single-language, single-market site, you do not need it.

When you need it

You have a clear case when any of these is true:

• The same content exists in multiple languages (English and Spanish product pages, for example).
• The same language is localized for multiple countries (en-US, en-GB, en-AU) with different pricing, spelling or availability.
• A mix of both: a global storefront with country folders and translated variants.

Commerce teams hit this early. If you are choosing between country domains, subfolders and subdomains before you scale, our breakdown of Shopify international domains walks through the URL decisions that hreflang then has to describe.

Build the values: language, region and URL

An hreflang value is a language code, optionally followed by a region code, separated by a dash. Language codes follow ISO 639-1 and region codes follow ISO 3166-1 Alpha 2, as laid out in Google’s localized versions documentation. Alternate URLs must be fully qualified, including the protocol (https://), not relative paths.

Two mistakes show up constantly:

1. Reversing the order. The language always comes first. US-en is invalid.
2. Using a region without a language. A region code alone does not describe a page. If you only serve one language per country, still write the language and region together.

A practical rule: use language-only values when the content is the same for everyone who speaks that language, and add the region only when you have a distinct page for that market.

Choose one implementation method

You have three ways to publish hreflang. Google documents all three and recommends choosing one and using it consistently, which avoids the maintenance problem of two sources disagreeing.

HTML link tags in the head

The most common method. Each page carries a set of link elements in its head:

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

This works well for sites with a modest number of locales, where the template can generate the block from a single translation map. It adds weight to every page, so a 30-locale site carries 30 lines per page.

HTTP response headers

Use headers for non-HTML files such as PDFs, where there is no head to place tags in. The same pairs of URL and code are sent in the response header. This method is rarely the right choice for ordinary pages.

XML sitemap

For large catalogs and many locales, the sitemap keeps the markup out of your templates. Each URL entry lists its alternates, including itself. It centralizes the logic in one generator, which makes auditing easier, and it keeps page weight flat. The tradeoff is that the sitemap must be regenerated whenever pages are added, removed or redirected.

Which one to pick

The single most useful decision is ownership. Whichever method you choose, one system should generate it from one source of truth, such as a mapping table of equivalent pages, rather than being hand-edited in several places.

Reciprocal, self-referencing and x-default

Three rules cause most failures in the field.

Self-reference. Every page in the cluster must list itself as well as every alternate version. The US page lists the US page, the UK page and the Mexican page.

Reciprocity. The links must be bidirectional. Google’s guidance is that if page A points to page B, page B must point back to page A. A one-way annotation is the classic reason hreflang gets ignored, usually because a template change updated one locale and not its siblings.

Think of a cluster the way you think of a tight set of internal links: every member references every other member. If you want the same logic applied to ordinary pages, internal linking fundamentals cover how reciprocal paths help crawlers, and our own piece on fixing internal linking gaps goes further on prioritizing them.

x-default. This is the fallback for users whose language or region does not match any version. Point it at your language selector page or your global default. It is a safety net, not a replacement for proper locale values.

When you do not have a full set

Not every page has an equivalent in every market. Google’s documentation notes that if complete bidirectional sets are hard to maintain, you can omit some languages on some pages, and Google still processes the links that point to each other. When you expand with a new market, link its pages bidirectionally to the originating or dominant language versions.

So a German page with no French twin simply omits French. Do not point it at an unrelated French page just to complete the grid, and do not point it at a redirect.

Canonicals, redirects and crawlability

Hreflang does not work in isolation. These neighbors can quietly break it.

Canonical tags must agree

Each localized page should canonicalize to itself, and hreflang annotations should only point at URLs that are themselves canonical. If your UK page has a canonical tag pointing to the US page, you are telling Google two different things: “this is an alternate version” and “this page is a duplicate of another.” Google will typically resolve that conflict by dropping one of the signals, and it is rarely the one you wanted.

Audit pairs together: for each URL in a cluster, confirm that the canonical equals the URL itself, the URL returns a 200 status, and the URL is indexable.

Avoid automatic IP-based redirects

Sending visitors to a regional version based on their IP address seems helpful. According to Google Search Central community guidance, it is strongly discouraged, because crawlers typically crawl from the US and never see your regional variations. A better pattern is to show a dismissible banner suggesting the visitor’s local version and let them choose.

Make rendered pages crawlable

If your hreflang tags are injected client-side or your locale switcher depends on JavaScript, confirm they appear in the rendered HTML crawlers see. Our JavaScript SEO audit shows how to check this in four steps.

Keep URL structure clean

Parameters, faceted URLs and inconsistent trailing slashes multiply the variants hreflang has to describe. If your catalog generates filtered URLs, resolve those first with faceted navigation SEO, and make sure the structure of each locale mirrors the others, as covered in SEO site architecture.

A rollout checklist

Use this order for a new international launch or a cleanup.

1. Map equivalents. Build a table of every page and its counterpart in each locale. Mark pages with no equivalent.
2. Decide the codes. Language-only where content is shared, language plus region where it differs. Add x-default.
3. Pick the method. One method, one generator, one source of truth.
4. Generate the annotations. Fully qualified URLs, self-reference included, reciprocal across the set.
5. Check the neighbors. Self-canonical, 200 status, indexable, no redirect chains in any annotated URL.
6. Test on staging. Crawl the staging environment with a tool that extracts hreflang and flags missing return links.
7. Release, then monitor. Re-crawl after launch and watch which URL Google shows per market.

Validating the result

Treat validation as three layers. First, a crawl: export every annotation and check that each target exists, returns 200 and links back. Second, spot checks: search from the target country or with the right language settings and see which URL appears. Third, Search Console: review indexing and coverage for your locale folders and look for pages Google has excluded as duplicates, which often signals a canonical conflict.

Rerun the crawl after every release that touches templates, navigation, redirects or the sitemap generator. Most hreflang failures in production are regressions, not first-launch mistakes.

Common mistakes and how to fix them

Also watch for two quieter problems. Staging or parameter URLs leaking into annotations is one. Another is translated pages that only translate the template and leave the body in the source language, which gives Google little reason to treat them as proper localized versions.

Our perspective

Most hreflang projects fail at the process level, not the syntax level. The tags are easy to write. What breaks them is that the page map lives in a spreadsheet, the templates live with engineering, the sitemap is owned by SEO, and the redirects are owned by whoever shipped last.

We treat hreflang as a system, not a snippet. We embed senior strategists with your team, and the same people who define the page map stay involved in building the generator, wiring it into your CMS or commerce platform, and writing the checks that fail a release when a return link goes missing. That is the difference between an annotation that is correct on launch day and one that is still correct a year later.

For multi-location brands, enterprise commerce organizations and B2B SaaS teams running several locales on complex stacks, this is where a single accountable partner pays off: one roadmap that covers the platform, the content model and the monitoring.

Service

Where to get help

If you are launching new markets or untangling an existing setup, we build and maintain this kind of infrastructure for scaling teams. Our growth platforms work covers the site architecture, localization model and tooling behind clean international SEO, and engagements are scoped around capacity plans starting at $3,500 per month.

If your stack spans commerce and a CRM, our work for enterprise commerce and B2B SaaS teams is a good place to see how we approach it.

FAQ

Does hreflang improve rankings?

Not directly. Community guidance from Google Search Central describes it as a signal for choosing the most appropriate localized URL, not a geotargeting ranking boost. Its value shows up in showing the right version to the right user.

Do I need x-default?

It is the fallback for users whose language does not match any listed version, and Google’s documentation includes it in the cluster rules. Point it at a language selector or your global default page. Most multi-market sites benefit from having one.

Can I mix HTML tags and a sitemap?

You can technically use more than one method, but Google recommends choosing one and using it consistently. Two sources invite contradictions, and contradictory annotations are harder to debug than missing ones.

What if some pages have no translation?

Omit that language on those pages. Google still processes the links that point to each other, so a partial set is fine. Just keep the pairs you do publish reciprocal.

Should I redirect users by location?

Automatic IP-based redirects are strongly discouraged in Google Search Central community guidance, because crawlers usually come from the US and cannot reach your regional pages. Offer a banner and a visible language or country selector instead.

Sources

• Localized Versions of your Pages, Google Search Central
• General Guide to Managing an International Website, Google Search Central Community
• Internal Linking for Clinic SEO: A Practical Guide

Recommended

• Internal Linking Strategy for SEO Teams: Fix Gaps, Not Link Counts
• Shopify International Domains: 3 URL Choices Before You Scale