All posts
Web design & development

Hreflang Explained: Setup and the Mistakes That Break It

Hreflang explained in plain terms: what the tags do, how to set them up, and the five mistakes that quietly make Google ignore them.

By Mehdi Hassan8 min read

The short answer

Hreflang is an HTML attribute that tells Google which language or regional version of a page to show each searcher. You set it up by listing every version of a page, including the page itself, on every version, with valid language codes, return links and an x-default fallback.

Key takeaways

  • Hreflang only works as a complete set: every version lists every other version and itself.
  • Use ISO language codes with optional region codes. en-GB is valid, en-UK is not.
  • Missing return tags are the most common reason Google ignores an hreflang cluster.
  • Add x-default for the page people should see when no version matches their language.
  • Pick one method (head tags, sitemap or headers) and remove duplicates that plugins add.

What is hreflang?

Hreflang is a signal that connects the language and regional versions of the same page, so a search engine can send a Spanish speaker to the Spanish page instead of the English one. It doesn't translate anything and it doesn't boost rankings. It only helps the right version win the slot your site already earns.

The tag lives in one of three places: a link element in the page head, an XML sitemap, or an HTTP header for files like PDFs. Each entry pairs a language code with an absolute URL. If you're still deciding how your languages should be organized at all, start with our multilingual website guide, then come back here for the tagging.

A typical set for one page with English, British English and German versions looks like this, repeated on all three pages:

  • <link rel="alternate" hreflang="en" href="https://example.com/pricing" />
  • <link rel="alternate" hreflang="en-GB" href="https://example.com/uk/pricing" />
  • <link rel="alternate" hreflang="de" href="https://example.com/de/preise" />
  • <link rel="alternate" hreflang="x-default" href="https://example.com/pricing" />

When do you actually need hreflang tags?

You need hreflang tags when the same content exists in more than one language or for more than one region, and you want each audience to land on its own version. A site that's only in English with one market doesn't need them at all, and adding them there just creates something else to break.

The case where hreflang matters most is regional variants in the same language. English pages for the US, the UK and Australia can look almost identical to a crawler, so without hreflang Google may pick one and fold the others into it as duplicates. With hreflang, it understands they're alternates for different audiences and can show the UK page to UK searchers, with its pound prices and local spelling.

For fully different languages the benefit is smaller, because the content already differs. Hreflang still helps there, mainly by stopping your English page from outranking your French page for French-language searches. How you structure those URLs is a separate decision, covered in our comparison of subdirectories, subdomains and country domains.

How do you set up hreflang step by step?

Set up hreflang by mapping every page to its equivalents first, then generating the tags from that map, not by hand-editing pages one at a time. Hand-edited hreflang drifts out of sync within weeks.

  1. Map equivalent pages

    Build a table with one row per page and one column per locale. If a page has no German version, leave the cell empty; never point a locale at an unrelated page like the home page.

  2. Choose your codes

    Use ISO 639-1 language codes (en, de, fr), adding an ISO 3166-1 region code only when you really target a country (en-GB, fr-CA). Keep the same codes in your URLs and your CMS so nobody has to translate between systems.

  3. Pick one delivery method

    Head tags are easiest to debug on a marketing site. Sitemaps suit large sites where the head is hard to edit. Use headers only for non-HTML files. Don't mix methods for the same pages.

  4. Generate the full set on every version

    Each page lists all its alternates, including itself, plus x-default. On Next.js this comes from the metadata alternates field; on Webflow and Framer, from the localization feature.

  5. Point only at canonical, live URLs

    Every URL in the set must return a 200 status, must not redirect, and must be the canonical version of that page. Hreflang pointing at a redirect or a noindexed page breaks the pair.

  6. Validate and monitor

    Crawl the site with a tool that checks hreflang return links, then spot-check the rendered HTML of a few pages. Re-check after every launch or migration.

What are the most common hreflang mistakes?

Five hreflang mistakes cause most broken setups: missing self-references, missing return tags, wrong codes, no x-default, and duplicate tags added by plugins or apps. Each one can make Google ignore some or all of the set without any error showing on the page itself.

Mistake

What it looks like

How to fix it

No self-reference

The German page lists English and French but not itself

Every page includes its own URL in the set

No return tags

English points to German, German doesn't point back

Generate tags from one shared map so links are always two-way

Wrong codes

en-UK, jp, es-LA, or a region with no language

Use language first, optional region second: en-GB, ja, es-419

No x-default

Visitors from unlisted locales get a random version

Point x-default at your language selector or main version

Duplicate tags

A plugin and the theme both output hreflang, with different URLs

Turn off every source but one, then re-crawl

Return tags deserve the most attention. Google treats hreflang as a claim that both pages have to confirm. If page A says page B is its German version but page B doesn't say the same about A, the claim is treated as unconfirmed. That protects sites from strangers declaring themselves your alternates, and it's also why one forgotten page can break a whole cluster.

How does hreflang x-default work?

The hreflang x-default value names the page to show when no other version in the set matches a searcher's language or region. It's a fallback, not a language. Most sites point it at their main language version or at a page where people choose their language.

Suppose your set covers English, German and French. A Dutch speaker matches none of them, so Google uses the x-default page. If that's your English page, the visitor gets English, which is usually right. If you run a global selector page that lets people pick a country, point x-default there instead.

x-default is optional in the spec, but leaving it out means you've handed the fallback decision to the search engine. It takes one extra line per page, so we include it on every multilingual build. It also pairs well with a clear language switcher, so a visitor who lands on the wrong version can fix it in one click.

Hypothetical example: a three-market SaaS site

For example, suppose a SaaS company sells in the US, the UK and Germany. Its pricing page exists at /pricing (US English), /uk/pricing (UK English, prices in pounds) and /de/preise (German, prices in euros).

Each of the three pages carries the same four tags: en-US for /pricing, en-GB for /uk/pricing, de for /de/preise, and x-default for /pricing. The US page uses en-US rather than plain en because a UK version exists, and the team wants Google to understand the split. Each page's canonical points at itself.

A year later the team adds Austria. Rather than a separate de-AT page with identical copy, they keep one German page and let the de tag cover Austrian searchers. Regional variants are only worth adding when something on the page actually differs, such as price, legal text or currency.

How do you check that hreflang is working?

Check hreflang by reading the rendered HTML of a few pages, crawling the whole site for missing return links, and watching which URLs Google shows in each country. No single report confirms it, so use all three.

  1. View the rendered source of one page per locale and confirm the full set is there, with absolute URLs and a self-reference.
  2. Run a crawler that reports hreflang errors, focusing on missing return links, non-200 targets and conflicting canonicals.
  3. In Search Console, compare which URL earns impressions for country-filtered queries. If UK searchers mostly see the US page, the set is being ignored.
  4. Repeat the crawl after any launch, redesign or platform change. Migrations are when hreflang breaks most often, which is why we wrote a separate guide to migration SEO for multilingual sites.

Google documents the full rules in its guide to localized versions of your pages, which is worth reading once if you own the setup. If your site runs on Next.js, our guide to Next.js i18n shows how to generate the tags from your routes so they can't drift.

Is hreflang worth the effort for a startup?

Hreflang is worth it as soon as you publish the same pages for more than one language or region, because the setup cost is small once it's generated from code or your CMS. It's not worth it for a single-language site, and it doesn't replace actually localizing the content.

The bigger risk for most startups isn't missing hreflang. It's translating pages that nobody has adapted to the market, then wondering why they don't convert. Our take on localization versus translation covers that side. Get the content right, generate hreflang from one map, and the tags become something you check after launches rather than something you fix every month.

Frequently asked questions

Does hreflang improve rankings?
No. Hreflang doesn't make a page rank higher. It helps Google swap in the right language or regional version for a searcher, so the version that ranks is the one that person can actually use. The indirect effect can be real, because visitors who land on their own language bounce less, but the tag itself is a routing signal, not a ranking boost.
Do I need hreflang if my languages are on different domains?
Yes, if the pages are equivalents. Hreflang works across domains, subdomains and subdirectories in the same way. The rules don't change: every version lists every other version and itself, and the links must be confirmed in both directions. Cross-domain sets are just harder to keep in sync, because each domain is often managed in a different place.
Can I use hreflang and a canonical tag on the same page?
Yes, and you should. Each language version should carry a canonical tag pointing at itself, plus the hreflang set. The conflict only appears when a translated page's canonical points at a different language version. That tells Google the page is a duplicate to drop, which cancels its hreflang.
Does Bing use hreflang?
Bing has historically leaned on other signals, such as the content-language meta tag, the page's language and its location signals, more than on hreflang. Adding hreflang does no harm for Bing, but if Bing traffic matters to you, also declare the page language in the html lang attribute and keep each language on clearly separate URLs.
Should every page have hreflang, or only translated ones?
Only pages that have at least one equivalent in another language or region need it. A blog post published only in English shouldn't carry hreflang pointing at the German home page. Missing translations should simply be left out of the set for that page, rather than filled with a loosely related URL.

· CEO & Design Director

Copywriter, designer and developer, and founder of Designify Studio. Over five years, 60+ projects across 14+ industries, for startups that have raised $300M+.

Want us to do this for you?

We take craft seriously over at Designify Studio. We do deep research and do what we do best - pay attention to the smallest details and make sure we speak to the right audience.

Schedule Call