Skip to content
Plumb
Light theme onCheck a URL

DocsGuides

hreflang

hreflang annotations tell search engines which pages are language or regional versions of each other, so each visitor sees the version for their language and country. They don't merge or rank pages; they swap the right URL into results.
  • Guide

Three Ways to Annotate

Use one method per page set; Google treats them equally.

1. HTML Link Elements

<link rel="alternate" hreflang="en-US" href="https://example.com/us/" />
<link rel="alternate" hreflang="en-GB" href="https://example.com/uk/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

In the <head> of every version, listing all versions including itself.

2. HTTP Link Header

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

For non-HTML files such as PDFs.

3. XML Sitemap

<url>
  <loc>https://example.com/us/</loc>
  <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/us/" />
  <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
</url>
<url>
  <loc>https://example.com/fr/</loc>
  <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/us/" />
  <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/" />
</url>

Every URL gets its own <url> entry with the full set. The urlset needs xmlns:xhtml="http://www.w3.org/1999/xhtml". Large sites usually prefer this: no page-weight cost, one place to maintain. The Sitemap Generator builds it from a CSV.

Values

  • Language: ISO 639-1 (en, de, zh), optionally followed by a region: ISO 3166-1 alpha-2 (en-GB, es-MX). A script is allowed too (zh-Hant, zh-Hant-TW).
  • A region alone isn’t valid: hreflang="gb" means a language that doesn’t exist, and uk is Ukrainian, not the United Kingdom (en-GB).
  • x-default marks the fallback for visitors matching no listed version (often a language selector or the international home page).
  • Values are case-insensitive. Use hyphens, not underscores.

Rules Google Enforces

  • Return links: if A lists B, B must list A. Annotations without a return link are ignored, so a page can’t claim another site’s page as its translation.
  • Self-reference: each version lists itself.
  • Canonical URLs only: annotate the URL each version is canonical to. Pointing to redirecting, noindex or non-canonical URLs breaks the cluster; don’t canonicalise all versions to one language.
  • Indexable, 200 pages: every URL in the set must return 200.
  • Fallbacks: with en-GB and en-US but no en, an English speaker in Canada may get either; add a language-only version or x-default to decide.

Not a Substitute for…

  • Translated content: versions should actually be localised; pages with the same content for different regions are fine (en-US vs en-GB) but shouldn’t be the only signal.
  • Automatic redirects: redirecting by IP or Accept-Language hides versions from Googlebot, which mostly crawls from the US without Accept-Language. Suggest the local version with a banner instead (check with the Locale-Adaptive Tester).