Hreflang Tags: Syntax, Examples and the Errors to Avoid

Hreflang tags are annotations that tell Google which language and country each version of a page is meant for, so a searcher in Germany sees your German page and a searcher in the UK sees your UK page. They take the form <link rel="alternate" hreflang="de" href="..."> in the HTML head, or the equivalent entries in an XML sitemap or HTTP header. Three rules decide whether they work: every version lists itself and all its alternates, every link is returned by the page it points to, and every code is a valid ISO language code with an optional ISO country code.

This guide walks through the syntax with copy-ready examples, compares the three implementation methods, explains x-default, and lists the errors that cause Google to quietly ignore your annotations. Everything here is checked against Google Search Central's documentation on localized versions.

What are hreflang tags and what do they do?

Hreflang tags group several URLs as localized versions of the same content so Google can serve the right one to each searcher.

Without them, Google has to guess. It may show your US pricing page to Australian visitors, or your English article to Spanish speakers when a Spanish version exists. Hreflang does not make a page rank higher on its own. It makes sure that when one of your versions qualifies to appear, the version shown matches the searcher's language and, if you specify it, their country.

Google recommends hreflang in three situations, according to its documentation on localized versions of your pages:

• You keep the main content in one language and translate only the template (navigation and footer), as many forum sites do.
• You have small regional variations in a single language, such as English pages for the US, UK and Ireland.
• Your site is fully translated into several languages.

Two facts surprise people. First, Google does not use hreflang or the HTML lang attribute to detect a page's language; it determines language algorithmically from the visible content. Hreflang tells Google how versions relate, not what language they are in. Second, localized pages are only treated as duplicates if the main content is left untranslated, so a properly translated page does not compete with its original.

Hreflang syntax: language and region codes

Every hreflang value is an ISO 639-1 language code, optionally followed by a hyphen and an ISO 3166-1 alpha-2 region code.

The language always comes first. You can target a language alone (de for German speakers anywhere) or a language in a specific country (de-CH for German speakers in Switzerland). You cannot target a country alone, because Google does not derive the language from a country code. Values are case-insensitive, though writing the region in uppercase (en-GB) follows the ISO convention and is easier to read.

For Spanish across Latin America, which trips up many sites, there is no single supported region code. Either use es for all Spanish speakers, or list each country you serve separately (es-MX, es-AR, es-CO) and point them at the same URL if the content is identical.

How to add hreflang tags: HTML, sitemap or HTTP headers

There are three equivalent ways to add hreflang tags, and you should pick one, because Google says using all three adds no benefit and makes mistakes harder to spot.

Method 1: link elements in the HTML head

Add one <link> element per version inside the <head>, including one for the page itself. The block is identical on every version of the page.

<head>
  <title>Pricing | Example</title>
  <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/" />
</head>

The tags must sit inside a well-formed <head>. If an invalid element closes the head early, tags after it can end up in the body, where they do not count. Google's documentation suggests pasting the rendered page into the W3C markup validator when in doubt.

Method 2: the XML sitemap

Each <url> entry gets an <xhtml:link> child for every version, including itself. Declare the xhtml namespace at the top.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/pricing/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/pricing/"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing/"/>
  </url>
  <url>
    <loc>https://example.com/de/preise/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/pricing/"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/preise/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/pricing/"/>
  </url>
</urlset>

With three versions of a page, the sitemap has three <url> entries, each with the same three children. The child links do not count toward the sitemap URL limit. A sitemap can only list URLs at or below the directory it is hosted in, so a sitemap at example.com/de/sitemap.xml cannot annotate example.com/pricing/.

Method 3: the HTTP Link header

For non-HTML files such as PDFs, send a Link header with the response. Every version returns the same header.

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

Which method should you use?

For a small site with two or three languages, HTML tags are the pragmatic choice because you can confirm them by viewing source. Move to the sitemap method when the tag block grows long or your platform makes template changes awkward. Many platforms do this for you: Shopify Markets, for example, adds hreflang tags automatically once each market has its own subfolder, subdomain or domain.

Self-reference, return links and x-default

Three rules turn a list of links into a working hreflang cluster: each page lists itself, each link is reciprocated, and an x-default covers everyone else.

Self-reference. Each language version must list itself as well as all the others. The German page's block includes a hreflang="de" line pointing at the German page. This is why the block is identical across versions.

Return links. If the English page says the German page is its de alternate, the German page must say the English page is its en alternate. If two pages do not both point to each other, Google ignores the tags. This is deliberate: it stops another site from declaring itself an alternate version of your pages. When maintaining a full set becomes hard on a large site, Google says you can omit some languages on some pages, but newly added language versions should always link bidirectionally to the original, strongest version.

x-default. The reserved x-default value names the page to show when no listed language or region matches the searcher. Google says it was designed for language selector pages and works best with them, but any page can be the x-default. For most small sites, the main-language version is the sensible choice. It needs no language code, because it serves users whose language you do not cover.

Language-only fallbacks. If you target English speakers in several countries (en-IE, en-CA, en-AU), Google suggests also providing a generic en page for English speakers elsewhere. That page can be one of the country versions.

Fully qualified URLs. Every href must be absolute and include the protocol: https://example.com/de/, not /de/ or //example.com/de/. Alternates can be on different domains, so a cluster can mix example.com and example.de.

Hreflang also interacts with canonical tags. Google's canonicalization documentation says that when you use hreflang you should specify a canonical page in the same language. In practice, each localized page canonicalises to itself. A canonical from the German page to the English one tells Google the German page is a duplicate, and the German version may never be shown.

Common hreflang tags errors and how to fix them

Most hreflang problems come from a short list of errors, and each one causes Google to ignore some or all of your annotations rather than raise a visible warning.

Redirected and broken targets are especially common after a site move or a slug change in one language. When you restructure, update the hreflang targets in the same release as the redirects, and add the check to your pre-migration checklist. The same goes for 301 redirects after a site move: every hreflang URL should point at the new final URL, never at one that redirects.

What to skip: do not add hreflang to pages that have no alternate version. A tag block on an English-only blog post that lists only itself adds nothing. Also skip IP-based or browser-language redirects to "help" hreflang along; Google advises against automatic redirects because they can stop users and crawlers from reaching every version.

How do you check that hreflang is working?

Check the rendered HTML of live pages, then watch Search Console data by country, because Google no longer offers a dedicated hreflang report.

Search Console's International Targeting report, which used to list hreflang errors, has been deprecated. Google still supports and uses hreflang; it just no longer reports on it directly. That leaves a three-part routine:

1. Inspect a live URL. Use the URL Inspection tool in Search Console and view the crawled HTML. Confirm the hreflang block appears inside the head, with absolute URLs and valid codes.
2. Spot-check reciprocity. Open two or three alternates from the block and confirm each lists the page you started from. For larger sites, a crawler or a hreflang testing tool (Google's documentation names some third-party options) checks every pair at once.
3. Watch country data. In the Performance report, filter by a target country and look at which URLs receive impressions. If searchers in Germany keep landing on English URLs while German versions exist, something in the cluster is broken.

If Bing matters to you, also set the HTML lang attribute correctly on each page and monitor language versions in Bing Webmaster Tools. The lang attribute is good accessibility practice anyway, even though Google ignores it for language detection.

Finally, remember the limits. Hreflang decides which of your versions to show; it does not decide whether you rank. A German page with no German keyword research and thin content will be correctly annotated and still invisible. Clear content structure, including structured data that matches the page, still does the ranking work in every language.

Frequently Asked Questions

Do hreflang tags help with ranking?

Hreflang tags do not raise a page's ranking on their own. They tell Google which language or regional version to show when one of your pages already qualifies to appear. The practical gain is that local searchers land on the right version, which usually improves clicks and conversions, while the ranking itself still depends on content quality and relevance.

Is hreflang x-default required?

No, x-default is optional, but it is recommended. It tells Google which page to show when a searcher's language or region matches none of your listed versions. Google says it was designed for language selector pages, though any page can serve. For a small site, pointing x-default at your main-language version is a sensible default.

Should hreflang go in the HTML or the sitemap?

Either works, because Google treats the HTML, sitemap and HTTP header methods as equivalent. HTML tags are easier to check page by page and suit small sites. Sitemaps suit large or many-language sites and keep page heads light. Choose one method and use it consistently, since combining methods adds no benefit and complicates debugging.

Can hreflang point to a different domain?

Yes. Google states that alternate URLs do not need to be on the same domain, so a cluster can include example.com, example.de and example.fr. The same rules apply: every URL must be fully qualified with https, every version must list itself and all others, and each link must be returned by the page it points to.

Why is Google ignoring hreflang tags?

The most common causes are missing return links, invalid codes such as en-UK, canonical tags pointing to another language, alternates that redirect or return errors, and tags placed outside a valid head section. Check the crawled HTML in Search Console's URL Inspection tool, confirm reciprocity between pairs, and make sure every target is a final, indexable URL.

Do I need hreflang for a single-language site?

Only if you have separate versions of pages for different countries in that language, such as US and UK pages with different prices or spelling. In that case use codes like en-US and en-GB. If one English page serves everyone, hreflang adds nothing, because there are no alternate versions for it to connect.

Get hreflang right once, then automate it

Correct hreflang comes down to valid ISO codes, a full self-referencing block on every version, reciprocal links, an x-default fallback, same-language canonicals and one implementation method. Generate the block from a single source of truth rather than editing pages by hand, and recheck it whenever URLs change.

The harder ongoing job is keeping every new article paired across languages, so no version goes live without its alternates. Agent Solo's Growth plan publishes in two languages with hreflang and canonicals set on every article, and the Scale plan supports up to five languages. If broken pairs keep your second market invisible, request early access.