Hreflang Tags: A Technical Guide With Correct Code Examples

Hreflang tags tell Google which URL serves which language and region, so a searcher in Lyon gets your French page and a searcher in Munich gets the German one. When they work, nobody notices them. When they break, your localized pages compete with each other, the wrong version shows up in the wrong country, and the budget you spent on translation earns very little.

We run international SEO for B2B SaaS companies in English, French, German, Italian and Spanish. Hreflang shows up in almost every technical audit we do. Every rule below is checked against Google Search Central's documentation on localized versions.

What an hreflang tag is

An hreflang annotation is a rel="alternate" link with an hreflang attribute. It declares that a URL has equivalent versions for other languages or regions. It also names the language (and optionally the region) each version targets. Google uses the set of annotations to swap in the right version for each searcher.

Google recommends hreflang in three situations.

• Translated templates: the main content stays in one language, but the navigation and footer are translated, which is common on user-generated content sites.
• Regional variants of one language: an English page for the US, the UK and Australia with different spelling, currency or pricing.
• Fully translated pages: the whole page exists in French, German, Spanish and so on.

Two facts set expectations correctly. First, Google says it does not use hreflang or the HTML lang attribute to detect a page's language. It reads the visible content for that, according to its guide to managing multi-regional sites. Hreflang only describes the relationship between versions. Second, hreflang does not make a page rank. It helps Google pick which of your equivalent URLs to show once the page already qualifies for the query.

How hreflang tags affect SEO and AI search

The SEO effect is mostly about choosing the right URL. Without hreflang, Google often shows your US page to UK searchers, or your English page to French searchers who would convert better in French. With regional variants in one language, the pages look nearly identical, so Google may fold them into one canonical and drop the others from results.

Google's canonicalization documentation adds a detail that many guides skip. When Google picks a canonical among duplicates, it prefers URLs that are part of a working hreflang cluster. So a clean hreflang set also protects your regional pages from being consolidated away.

AI search runs on the same foundation. Google states that there are no extra technical requirements to appear in AI Overviews or AI Mode beyond being indexed and eligible for a snippet. A French page that Google never indexes, or that it folds into the English canonical, cannot be cited in a French AI Overview. Assistants like ChatGPT, Perplexity and Gemini can only cite a localized page their crawlers can fetch and read. We see this in client data. For an ecommerce marketing platform with native-language sites across Europe, AI referral users grew 522% in France and 281% in Spain over the three months to May 2026.

Hreflang syntax and language codes

Every annotation has the same three parts. The rel="alternate" value marks the link as an alternate version. The hreflang value names the audience. The href value gives the full URL of that version.

The hreflang value follows strict rules from Google's documentation.

• The first part is a language code in ISO 639-1 format, such as en, fr, de, it or es.
• The optional second part is a region code in ISO 3166-1 Alpha 2 format, such as us, gb, fr, de or ch.
• A region code on its own is invalid. Google does not derive the language from a country, so hreflang="de" means German speakers anywhere. A value of hreflang="ch" alone is invalid as a region.
• Codes are case-insensitive. Uppercase regions (en-GB) are a convention only.
• Codes outside those standards are unsupported. Google names es-419 (Latin American Spanish) as an example it does not accept.
• Scripts use ISO 15924 codes, such as zh-Hant for Traditional Chinese or zh-Hans-CN.

Many of the code errors we fix come from intuition. The United Kingdom's region code is gb, so the correct value for British English is en-gb. uk is the ISO 639-1 language code for Ukrainian, which means hreflang="uk" targets Ukrainian speakers. As a region, UK is a reserved code that Google ignores. The same trap catches teams who write la for Los Angeles (that is the language code for Latin, and the region code for Laos) or eu for Europe (Basque as a language, a reserved code as a region).

Three ways to implement hreflang, with code examples

Google treats the three methods as equivalent and states that using more than one adds no benefit. Pick one per page type and use it everywhere. Mixing methods across a site makes audits harder and invites conflicting signals.

The examples below use a site with English for the US, English for the UK, French for France, German for any German speaker, and an x-default fallback.

HTML link elements in the head

Every version carries the full set of link elements inside its <head>, including a link to itself.

html <head> <title>Pricing | Example</title> <link rel="alternate" hreflang="en-us" href="https://www.example.com/pricing/" /> <link rel="alternate" hreflang="en-gb" href="https://www.example.com/uk/pricing/" /> <link rel="alternate" hreflang="fr-fr" href="https://www.example.com/fr/tarifs/" /> <link rel="alternate" hreflang="de" href="https://www.example.com/de/preise/" /> <link rel="alternate" hreflang="x-default" href="https://www.example.com/pricing/" /> </head>

The same five lines go on all four pages. Google's rules for this method are specific.

• Use fully qualified URLs with the protocol. Relative paths like /fr/tarifs/ and protocol-relative URLs like //www.example.com/fr/tarifs/ are not supported.
• Give each annotation its own <link> element. Do not combine hreflang with other attributes such as media.
• Keep the elements inside a well-formed <head>. An element that browsers only allow in the body, such as an img or iframe, can close the head early, and any hreflang links after it end up outside the head.

HTML suits sites with a modest number of URLs per language. On larger sites, a full set of link elements adds weight to every page. The sitemap method is easier to maintain at that scale.

HTTP Link headers for PDFs and other non-HTML files

Use HTTP headers when the localized asset is not an HTML page, such as a PDF whitepaper in four languages. The server returns one Link header listing every version, separated by commas.

http HTTP/1.1 200 OK Content-Type: application/pdf Link: <https://www.example.com/en/guide.pdf>; rel="alternate"; hreflang="en", <https://www.example.com/fr/guide.pdf>; rel="alternate"; hreflang="fr", <https://www.example.com/de/guide.pdf>; rel="alternate"; hreflang="de", <https://www.example.com/en/guide.pdf>; rel="alternate"; hreflang="x-default"

The header must include the requested file itself. It must also be identical on every version. In practice, your developer sets this in the web server or CDN configuration. A quick curl -I request against each file shows whether the header is present.

XML sitemap annotations for large sites

The sitemap method keeps hreflang out of the page code entirely. Each <url> entry lists its own <loc> and an xhtml:link child for every version, including itself. The sitemap must declare the xhtml namespace.

```xml

https://www.example.com/pricing/ https://www.example.com/uk/pricing/ https://www.example.com/fr/tarifs/ ```

Every version needs its own <url> block that repeats the full set. A sitemap with only the English URLs and a list of alternates underneath them is incomplete. Standard sitemap limits still apply. A sitemap can only list URLs at or below the directory where it is hosted. Submit the sitemaps in Search Console. If you split sitemaps by language, submit every one of them.

Self-references, return links and x-default

Self-referencing annotations

Each version must list itself alongside every other version. Google's documentation requires the set of annotations to be identical on every page in the cluster. The English page lists English, British English, French and German. The French page lists the same four. Generating the set from one source of truth in your CMS, rather than typing it per page, is the simplest way to keep the sets identical.

Return links

Hreflang only works in both directions. If the US page names the French page as an alternate, the French page must name the US page in return. Google states that when two pages do not both point to each other, it ignores the annotations. The rule exists so that another site cannot declare itself an alternate version of your pages. Google lists missing return links first among the common hreflang mistakes in its troubleshooting section.

Google also allows partial sets. You can leave some languages off some pages. Google still processes the pairs that confirm each other. When you add a new market, link the new pages to at least the original or dominant language versions. Add the return link on those pages in the same release.

x-default

The reserved x-default value names the page to show when no other version matches the searcher's language or region. It takes no language code. Google says it works best on language or country selector pages and on home pages that redirect users by location. A typical setup points x-default to the global English page or to a selector page.

Without x-default, a searcher in Brazil on a site with English, French and German versions gets whichever version Google judges best. With x-default, you choose that page yourself.

Hreflang and canonical tags

Canonicals and hreflang must agree. Conflicts between them cause some of the costliest errors we find.

• Every localized page should be its own canonical. The French pricing page carries rel="canonical" pointing to the French pricing page. Google's guidance is to specify a canonical in the same language, or the best possible substitute language when none exists.
• Never canonicalize a translation to the English original. A French page with a canonical pointing to the English page asks Google to drop the French URL from results. The hreflang annotation then points to a URL that is not indexed.
• Hreflang URLs must be canonical URLs. Annotations should list the exact canonical version of each page, with the same protocol, host and trailing slash convention. An annotation pointing to http:// or to a non-www URL that redirects breaks the cluster. Google also says not to list HTTP URLs in hreflang annotations or sitemaps.
• Hreflang belongs on rel="alternate" only. Google states that canonical annotations carrying hreflang, lang, media or type attributes are not used for canonicalization.

Regional variants in one language need extra care. When your US and UK pages are nearly identical, Google may still choose one as canonical for both, even with correct hreflang. Localize what differs in practice, such as prices, currency, spelling, legal references and customer examples, so each page earns its place.

Common hreflang errors and how to fix them

Google's International Targeting report in Search Console is deprecated, so we rely on a crawler to find these problems at scale. The table lists the errors we see in client audits and the fix for each.

The last row needs context. Google advises against automatically redirecting users between language versions and against using IP analysis to adapt content. Googlebot usually crawls from US IP addresses and does not send an Accept-Language header, according to its documentation on locale-adaptive pages. A site that redirects visitors by location can show Googlebot only the US version, even with flawless hreflang code.

How to audit hreflang with Screaming Frog

We run every technical audit on Screaming Frog SEO Spider crawls. The steps below follow Screaming Frog's own hreflang audit guide, plus the checks we have added after finding problems a default crawl misses.

1. Turn on hreflang crawling. Under Configuration, then Spider, then Crawl, enable the options to crawl and store hreflang. This makes the crawler follow and report every URL referenced in your annotations.
2. Add sitemaps if hreflang lives there. In the same Crawl settings, enable Crawl Linked XML Sitemaps, and either let the crawler find the sitemaps through robots.txt or enter the sitemap URLs directly.
3. Include every domain in the cluster. If your markets sit on separate ccTLDs or subdomains, add them so the crawler processes their HTML instead of treating them as external links.
4. Turn on JavaScript rendering for JavaScript sites. Under Configuration, then Spider, then Rendering, choose JavaScript. A text-only crawl reads the server response and misses client-side redirects and content injected by scripts.
5. Run the crawl, then run Crawl Analysis. Crawl Analysis populates the Unlinked Hreflang URLs filter, which lists alternate URLs that no internal link reaches.
6. Work through the Hreflang tab. The filters map directly to the error table above. They include Missing Return Links, Inconsistent Language and Region Return Links, Non Canonical Return Links, Noindex Return Links, Non-200 Hreflang URLs, Incorrect Language and Region Codes, Missing Self Reference, Not Using Canonical, Missing X-Default, Multiple Entries, Missing, and Outside head.
7. Check redirects in the Response Codes tab. With rendering on, the Redirection (JavaScript) filter catches pages that return a 200 to the crawler and then send users somewhere else.
8. Export and ticket. Use the Reports menu for the hreflang bulk exports, then turn each issue into a ticket with the affected URLs, the exact fix, an owner and a verification step. A developer should be able to fix each ticket without asking a follow-up question.

After the fixes ship, recrawl the affected sections and confirm the filters are empty. Then check the URL Inspection tool in Search Console for a sample of localized pages, and confirm Google selected each page as its own canonical.

How Flying Cat handles hreflang on client multilingual sites

Hreflang problems rarely show up as hreflang errors. They show up as a market that never grows. In our technical SEO audits, the cause is often a redirect, a rendering issue or a canonical conflict sitting next to the hreflang code.

Valid hreflang on pages that redirected to the US

During a content audit for an AI tax research platform for accountants, we noticed its Canada and UK sections drew almost no traffic. The pages returned a 200 status and carried hreflang tags, so a standard crawl reported them as healthy. A JavaScript-rendered crawl told a different story. 99.9% of the Canadian answer pages redirected client-side to their US versions. Visitors who landed on a Canadian URL ended up on the US page, so the Canadian annotations pointed at content nobody could stay on. A plain crawl would have missed it, which is why step 4 of our audit is never optional on JavaScript sites.

French pages served to Google as an empty English shell

After a vertical SaaS client in veterinary software moved its site to a JavaScript app, we checked every French page we had published. Every one served Googlebot the same empty shell with an English title, so the French content was invisible to Google. The pages were already losing clicks. The same audit found the www and non-www hosts splitting ranking signals, because the canonical tags pointed to URLs that redirected. The client's team replaced hundreds of internal www links, then fixed hundreds more links across dozens of posts. Before the re-platform, this French site had doubled its clicks and nearly tripled its impressions soon after we started publishing French pages, which shows how much was at stake.

Native pages first, then clean annotations

Hreflang only pays off when each version deserves to rank in its market. For an ecommerce marketing platform, translated pages sat in the mid-20s in France. Native writers rebuilt each market around local search habits, retail calendars, regulations and customer examples. The client tripled its top-3 keyword rankings in France within six months. Organic conversions in France grew 60% in year one. For ActiveCampaign, we localized the best English pages and wrote new bottom- and mid-funnel pages for the French, Italian, German and Spanish sites. Those sites gained 83,000+ more non-branded clicks in eight months.

Our hreflang checklist for client sites

• We map every URL to its alternates in a spreadsheet before development starts, with one row per page and one column per market, so the developer works from one source of truth.
• We confirm the URL structure (ccTLDs, subdomains or subfolders) and pick a single implementation method for each page type.
• We set self-referencing canonicals on every version and check that hreflang lists only those canonical URLs.
• We crawl with JavaScript rendering on any site built on a JavaScript framework and compare it with a text-only crawl.
• We ship new markets with return links in the same release and recrawl within a week.
• We recheck the cluster after every migration, re-platform or URL change, since those events break hreflang more often than anything else we see.

The translation side follows the same discipline. Our guides on multilingual SEO and localization versus translation for SaaS cover how we build the pages that hreflang connects. Our list of international SEO mistakes covers the strategic errors that hreflang cannot fix.

Frequently asked questions about hreflang tags

Do I need hreflang if my site only has one language?

A single-language site with no regional variants does not need hreflang. The annotation only applies when a page has equivalent versions for other languages or regions. Set the HTML lang attribute correctly instead.

Does hreflang work for Bing?

Bing's published guidance on telling Bing your site's country and language names the content-language meta tag and HTTP header, the HTML lang attribute, country-code domains and server location as its signals. It does not mention hreflang. For sites with meaningful Bing traffic, we keep hreflang for Google and also set the lang attribute on every localized page.

Can hreflang point to a different domain?

Hreflang can point to a different domain. Google supports alternates across domains, such as example.com for the US and example.de for Germany. The same rules for return links, self-references and absolute URLs apply.

Should I use hreflang for regional versions in the same language?

Use hreflang for same-language regional versions when they differ in ways searchers care about, such as price, currency or spelling. Use language plus region codes like en-us, en-gb and en-au, add an x-default, and localize enough of each page that Google treats them as distinct.

How long does it take Google to process hreflang changes?

Google processes annotations as it recrawls the pages in the cluster, so timing depends on crawl frequency. Frequently crawled pages update sooner than deep pages. Submitting updated sitemaps and keeping internal links to every localized page helps Google find the changes sooner.