All glossary terms
Glossary Spec

xhtml:link rel="alternate" hreflang

A sitemap extension declaring language and regional variants of a URL. Used instead of (or alongside) HTML `<link rel="alternate" hreflang>` tags.

Also known as: hreflang sitemap, international sitemap

hreflang in sitemaps is the XML-native way to declare language and regional alternates for a URL. It uses the xhtml:link namespace and replaces (or complements) HTML <link rel="alternate" hreflang> tags in the <head>.

Why use the sitemap form

For sites with hundreds or thousands of localized URLs, declaring hreflang in HTML tags has two problems:

  1. Page weight. Every page must list every alternate, growing N² with locales.
  2. Sync drift. If the HTML tags get out of sync (one page lists 10 alternates, another lists 9), Google often discards the entire cluster.

The sitemap form centralises hreflang declarations in one auditable XML file, makes bulk updates simpler, and avoids the per-page bloat.

Anatomy

<?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/en/page</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/page"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/page"/>
  </url>
  <url>
    <loc>https://example.com/es/page</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
    <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/page"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/en/page"/>
  </url>
</urlset>

Critical rule: every URL in the cluster must list every other URL plus itself. Missing self-references is the #1 cause of "hreflang errors" in Google Search Console.

hreflang values

  • Language only: en, fr, de, es, ja
  • Language + region (ISO 3166-1 Alpha-2): en-US, en-GB, es-MX, es-ES, fr-CA
  • x-default: the fallback page for users whose language doesn't match any explicit alternate

Common mistakes

  • Forgetting self-reference. Each URL must include itself in its own cluster. <xhtml:link rel="alternate" hreflang="es" href="https://example.com/es/page"/> inside the <url> for the Spanish page.
  • Asymmetric clusters. /en/page lists /es/page as an alternate, but /es/page doesn't list /en/page back. Google drops asymmetric pairs.
  • Mixing HTML and XML forms. Pick one. If you use both, ensure they're identical — if they conflict, Google may use either and ignore the rest.
  • Using _ instead of -. Correct: en-US. Incorrect: en_US.
  • Region without language. Invalid. hreflang="US" doesn't mean anything; you need en-US or es-US.

What SitemapHost does

The SitemapHost API accepts an hreflang array per URL. We emit the correct xhtml:link markup, validate cluster symmetry, and warn at generation time if any URL in a hreflang cluster is missing its peers.

Related terms

Need help managing your sitemaps?

SitemapHost hosts your XML sitemap at your own domain with auto-SSL, IndexNow, and GSC integration.

Get Started Free