H
Hreflang Generator

How to Add Hreflang Tags to Your XML Sitemap

Add hreflang annotations to your XML sitemap with xhtml:link elements. Full syntax guide with examples for multilingual and multi-regional sites.

Adding hreflang to your XML sitemap is an alternative to placing <link> elements in each page's HTML. It centralises your hreflang signals, which makes them easier to manage at scale -- but it comes with its own syntax requirements and gotchas.

Why use the sitemap method?

For small sites, adding hreflang to each page's <head> is straightforward. But when you have thousands of pages in multiple languages, maintaining HTML-level hreflang becomes a significant engineering problem.

The sitemap approach lets you manage all hreflang annotations in one place. Your CMS or build process generates the sitemap, and Google reads the language signals from there instead of from each page's HTML.

Both methods are supported. You don't need both -- pick one and be consistent.

The xhtml namespace

Sitemap hreflang uses xhtml:link elements, which require the xhtml namespace to be declared on your <urlset> tag. This is the part most developers miss first.

<?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">

Without that xmlns:xhtml declaration, your xhtml:link elements are invalid and Google will ignore them.

Full example: multilingual sitemap

Here's a complete example for a site with English, French, and German versions of two pages:

<?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">

  <!-- English about page -->
  <url>
    <loc>https://example.com/en/about/</loc>
    <xhtml:link rel="alternate" hreflang="en"
                href="https://example.com/en/about/" />
    <xhtml:link rel="alternate" hreflang="fr"
                href="https://example.com/fr/about/" />
    <xhtml:link rel="alternate" hreflang="de"
                href="https://example.com/de/about/" />
    <xhtml:link rel="alternate" hreflang="x-default"
                href="https://example.com/en/about/" />
  </url>

  <!-- French about page -->
  <url>
    <loc>https://example.com/fr/about/</loc>
    <xhtml:link rel="alternate" hreflang="en"
                href="https://example.com/en/about/" />
    <xhtml:link rel="alternate" hreflang="fr"
                href="https://example.com/fr/about/" />
    <xhtml:link rel="alternate" hreflang="de"
                href="https://example.com/de/about/" />
    <xhtml:link rel="alternate" hreflang="x-default"
                href="https://example.com/en/about/" />
  </url>

  <!-- German about page -->
  <url>
    <loc>https://example.com/de/about/</loc>
    <xhtml:link rel="alternate" hreflang="en"
                href="https://example.com/en/about/" />
    <xhtml:link rel="alternate" hreflang="fr"
                href="https://example.com/fr/about/" />
    <xhtml:link rel="alternate" hreflang="de"
                href="https://example.com/de/about/" />
    <xhtml:link rel="alternate" hreflang="x-default"
                href="https://example.com/en/about/" />
  </url>

</urlset>

Notice: all three pages appear as their own <url> blocks, and each block contains the full set of xhtml:link annotations -- including a self-referencing link.

Generate sitemap-ready hreflang annotations

Paste your URLs and get the complete XML sitemap markup with correct hreflang xhtml:link elements.

The self-referencing requirement

Just like HTML-based hreflang, every URL block in the sitemap must include a self-referencing xhtml:link -- a link to its own URL with its own language code. The French page must link to itself with hreflang="fr".

Missing the self-referencing tag is an error Google will silently ignore rather than surface. The hreflang signals for that page may not be processed correctly.

Every URL block needs the complete set

A common mistake is including xhtml:link elements only on the "primary" language URL blocks and leaving them off the others. Every URL in the hreflang group must appear as a <url> block with the full set of annotations.

Sitemap size and performance

Google's sitemap size limits apply to hreflang sitemaps the same way they apply to standard sitemaps:

  • Maximum 50,000 URLs per sitemap file
  • Maximum 50MB uncompressed per sitemap file

With hreflang, your sitemap grows proportionally with the number of languages. A site with 10,000 pages in 5 languages has 50,000 URL blocks -- right at the limit. Use sitemap index files to split across multiple sitemaps.

Compress your sitemaps

Hreflang sitemaps get large quickly. Gzip compression is supported and can reduce file size by 70-80%. Most sitemap generators handle this automatically.

Combining with lastmod and changefreq

You can include standard sitemap elements alongside xhtml:link annotations:

<url>
  <loc>https://example.com/en/about/</loc>
  <lastmod>2024-01-15</lastmod>
  <xhtml:link rel="alternate" hreflang="en"
              href="https://example.com/en/about/" />
  <xhtml:link rel="alternate" hreflang="fr"
              href="https://example.com/fr/about/" />
</url>

The order doesn't matter. Google processes all child elements within each <url> block.

Validating your sitemap

After creating or updating your hreflang sitemap:

  1. Submit it in Google Search Console via Sitemaps
  2. Check for any processing errors -- GSC will report malformed XML or namespace issues
  3. Use a hreflang validator to check for missing return links and self-referencing errors
  4. Monitor Coverage reports for any indexing issues after submission

If GSC reports your sitemap was processed but you see no hreflang signals taking effect in search, check that your pages aren't blocked by robots.txt -- Google needs to crawl the pages themselves, not just read the sitemap.

Sitemap vs. HTML: which to choose?

Use the sitemap method if:

  • You have a large site (hundreds or thousands of pages per language)
  • Your CMS makes it difficult to modify individual page templates
  • You want centralised management of international SEO signals

Use HTML link elements if:

  • You have a small to medium site
  • Your CMS or framework handles <head> injection cleanly (most do)
  • You want hreflang signals visible to crawlers without sitemap dependency

Related Articles

Part of Boring Tools -- boring tools for boring jobs.

Generate perfect hreflang tags

Create and validate hreflang markup for your multilingual site. Free.