Hreflang: How to Set Up Language and Country Versions Correctly

In short: hreflang tells Google which language or country version of a page to show each searcher. Every version lists every version, including itself, with an ISO 639-1 language code and an optional ISO 3166-1 alpha-2 region (en, de, en-GB, pt-BR), plus an optional x-default fallback. Links must be absolute and must point both ways, or Google ignores them. Each version needs a self-referencing canonical; a canonical that points to another language cancels the setup. Google detects the page language from the content, so the translation itself has to be real.

International sites lose traffic in a quiet way. The English page ranks in Germany, the Spanish page shows up in Mexico when you built a Mexican one, or the UK store appears for American searchers with prices in pounds. Nothing is broken on the site; Google simply guessed which version to show. hreflang is how you stop it guessing.

This guide explains how hreflang works according to Google's documentation, the code rules that trip most sites, how canonicals interact with it, what our free hreflang checker tests, and how to fix each problem.

What hreflang does, and what it doesn't

hreflang annotations describe a set of pages that are versions of each other: the same content in another language, or the same language adapted for another country. Google uses them to show the matching version in its results.

What it does not do:

• It does not detect language. Google says it "doesn't use hreflang or the HTML lang attribute to detect the language of a page"; it uses the visible content (multi-regional sites). A page tagged de with English text is an English page.
• It does not make thin translations into duplicates or originals. Google says localized versions "are only considered duplicates if the main content of the page remains untranslated." A page with a translated menu and English body text is a duplicate.
• It does not redirect anyone. It only changes which URL appears in results. Visitors can still open any version.

The three ways to add hreflang

Google says the three methods "are equivalent from Google's perspective." Use one per page; mixing them just adds places for errors.

1. HTML link elements in the <head>, the most common choice. On https://example.com/en/pricing:

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

The German and French pages carry exactly the same four lines. Google requires the tags to be "inside a well-formed <head> section"; a stray element that the browser moves into the body, such as an image or an unclosed tag above the links, can break the head early.

2. HTTP Link headers, the only option for non-HTML files such as PDFs:

Link: <https://example.com/en/guide.pdf>; rel="alternate"; hreflang="en",
      <https://example.com/de/guide.pdf>; rel="alternate"; hreflang="de"

Google says the header must be identical for every version.

3. XML sitemap, convenient for large sites because no template changes are needed:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/en/pricing</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise"/>
  </url>
  <url>
    <loc>https://example.com/de/preise</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise"/>
  </url>
</urlset>

Each <url> lists every version, including itself.

The rules Google enforces

Return links and self-reference

"If two pages don't both point to each other, the tags will be ignored." This is the rule behind most broken setups. If the English page lists the German page but the German page does not list the English one, Google drops the pair. Google also says "each language version must list itself."

Language and region codes

"Only language codes listed in ISO 639-1 and region codes listed in ISO 3166-1 Alpha 2 are supported." The language comes first; the region is optional. Google also supports script subtags for languages written in more than one script, such as zh-Hant and zh-Hans, and combinations like zh-Hans-US.

For Spanish across Latin America, either use es for one shared Spanish version, or list the specific countries you target (es-MX, es-AR, es-CO) pointing to the same URL.

x-default

"The reserved x-default value is used when no other language/region matches the user's browser setting." Point it at a language selector or your main international version. It is optional but useful: without it, a searcher in a language you do not offer gets whichever version Google picks.

Absolute URLs

"Alternate URLs must be fully-qualified, including the transport method." https://example.com/de/ works; /de/ and //example.com/de/ do not.

hreflang and canonical tags

The two must agree. Each version should have a canonical pointing to itself, not to the English or main version. Google's canonicalization guide says to "specify a canonical page in the same language," or "the best possible substitute language if a canonical page doesn't exist for the same language," and notes that hreflang clusters influence canonical choice, favoring URLs that link to each other reciprocally.

The classic mistake: every language version carries <link rel="canonical" href="https://example.com/en/...">. That tells Google the other versions are duplicates of the English page, and they drop out of the index along with their hreflang annotations.

Two more conflicts to avoid: hreflang URLs that redirect (list the final URL) and hreflang URLs that carry noindex (a version Google cannot index cannot be shown).

Site structure and automatic redirects

Google's multi-regional guide compares the URL structures:

Whichever you choose, do not redirect visitors automatically by IP or browser language. Google says this "could prevent users (and search engines) from viewing all the versions of your site," and that Googlebot "usually originates from the USA." Show a suggestion banner instead and let hreflang handle search results.

How the Searvia hreflang checker works

The hreflang checker runs the same engine as our website SEO checker: you enter a domain or a page address, it audits that page (your home page if you enter only a domain) and the site files around it with 38 checks in about 20 seconds, and puts the three checks this tool is about first. This is exactly what they test.

Language versions, hreflang (low priority). The checker reads every <link rel="alternate" hreflang="..." href="..."> element in the HTML of that page, after following redirects to its final address.

• If there are none, the result is informational: "No language versions are declared (fine for a single-language site)." It does not affect your grade.
• Each code is checked against the codes Google supports: x-default, or a two-letter ISO 639-1 language, optionally followed by a four-letter script (zh-Hant) and a two-letter ISO 3166-1 alpha-2 country (pt-BR, en-GB). A common mistake such as en-UK is marked with its fix (→ en-GB); es-419, three-letter languages and other codes Google does not accept are marked as not valid. Each row in the report shows the code, its URL, a check or a cross and that note. Up to 20 rows are shown.
• It checks for a self-reference: one of the listed URLs must be the page itself. The comparison ignores http versus https, a leading www., query strings and a trailing slash.
• Pass when every code is valid and the page lists itself; if there is no x-default, the message adds that this optional fallback is missing. Otherwise a warning with "The language versions do not include this page itself" or "Some language codes are not valid."

Page language (low priority). Passes when the <html> element has a lang attribute and shows its language; warns when it is missing.

Canonical URL (medium priority). Passes when the canonical tag points to the page itself; warns when it is missing or points to another address, showing that address.

What it does not test

• Return links. The checker reads one page and does not fetch the other versions, so it cannot confirm that they link back. Open each version's source, or use a site crawler, to check reciprocity.
• HTTP headers and sitemaps. Only HTML <link> elements are read. If you declare hreflang in a sitemap, the checker reports no versions.
• Absolute URLs and duplicates. Relative URLs are resolved instead of flagged, and if the same code appears twice, only one is kept.
• Other pages. One page is checked per run. Enter the address of each version you want to check (example.com/de/pricing, de.example.com), or use a crawler for the whole site.

Reading the result

The overall A+ to F grade covers all 38 checks, weighted by priority (high 10, medium 5, low 2; warnings earn half), with a "Fix these first" list and a shareable report.

How to fix every hreflang problem

1. No language versions are declared, but you have them

1. List every version of the page and its full URL, for example /en/, /de/, /fr/.
2. Pick a method: HTML tags for most sites, the sitemap if templates are hard to change.
3. Generate the tags from one source in your code or CMS, so every version outputs the same complete set. Hand-written tags drift.
4. If you use a multilingual plugin or your platform's built-in markets feature, it usually outputs hreflang for you; check that every translation is linked to its original and published, because unlinked translations get no tags.
5. Rerun the hreflang checker.

2. The language versions do not include this page itself

Add a line for the current page with its own code. In a template, this usually means the loop over languages skips the current language; remove that condition. Make sure the self URL is the canonical URL, with the same protocol, host and trailing slash convention.

3. Some language codes are not valid

1. Find the rows with a cross in the report.
2. Fix the format: hyphen not underscore, language first, region second (en-GB, not GB-en).
3. Replace unsupported codes: en-UK becomes en-GB (the report suggests it), es-419 becomes es or a list of country codes, three-letter codes become two-letter ones.
4. Check the code is the language you mean: be is Belarusian, cz is not a language code (Czech is cs), jp is not a language code (Japanese is ja), dk is not one (Danish is da).

4. The page does not declare its language

Add the language to the root element, for example <html lang="en"> or <html lang="pt-BR">. Google does not use it to detect language, but browsers, translation tools and screen readers do, as MDN describes.

5. The canonical points to another address

On a multilingual site this is often the cross-language canonical problem. Change each version's canonical to its own URL. If the canonical points to the same page in another form (http instead of https, or without www), make it match your final address exactly.

6. Return links are missing (not tested by the checker)

Open two versions side by side and compare their hreflang lists: they must be identical sets. If they differ, the cause is almost always the template or plugin that generates them, so fixing the generator once fixes every page.

Worked example (hypothetical)

The following is a hypothetical example, not real data. Kestrel Gear, an invented outdoor brand, runs example.com in English with /de/, /fr/ and /es/ versions. German searchers keep landing on English pages. The hreflang checker reports:

Canonical: "The canonical URL points to the page itself." Page language: en.

The cross on es_ES is a format error. The cross on en-UK comes with the note "→ en-GB": Google does not accept UK as a region, so the English page had no usable annotation. Viewing the German page's source finds a third: its canonical points to the English home page, so Google treated /de/ as a duplicate. The fixes:

1. Changed the codes to en, de, fr, es (one version per language, no regions needed) and added x-default pointing to the English home page.
2. Moved the hreflang output into one shared template so every version prints the same set, including itself.
3. Gave each version a self-referencing canonical.
4. Removed an IP-based redirect that sent visitors from Germany to /de/ automatically, replacing it with a suggestion banner.

A 20-minute hreflang checklist

1. Run the free hreflang checker on your home page and on each language version.
2. Compare every code against ISO 639-1 and ISO 3166-1 alpha-2.
3. Confirm each version lists itself and every other version.
4. Open two versions and confirm the sets are identical.
5. Check that each version's canonical points to itself.
6. Add x-default (optional, but useful).
7. Make sure no automatic redirect hides versions from Googlebot.

How Searvia helps

The free hreflang checker validates the hreflang links, page language and canonical of the page you enter in one shareable report, alongside the other checks of the website SEO checker. In a Searvia account, connect Search Console to see clicks and positions by country for each language version, and run the site audit every week to catch canonicals pointing elsewhere, duplicate titles across language versions and broken pages. If you publish apps as well as websites, our App Store localization guide covers the same problem on the store side. For the full technical checklist, see the technical SEO audit guide.