Fixing Sitemap and HTML Hreflang Mismatches

Why two sources drift apart

Google treats the three declaration methods, HTML link tags, HTTP headers and sitemaps, as equivalent. Using more than one is allowed. The trouble is that they are rarely produced by the same code. A typical WordPress site might have WPML printing link tags and an SEO plugin building the sitemap; a custom site might have hreflang in a template and a nightly job writing the sitemap from the database. Each reads the site at a different time, from a different place, with different rules for building addresses.

When the two agree, the duplication is harmless but pointless. When they disagree, you are sending Google two versions of the same cluster, and there is no documented rule for which one wins. Google may combine them, prefer one, or distrust the relationship. You lose control of which page is shown where.

The kinds of mismatch

Comparing the two sources properly

Eyeballing a sitemap next to page source works for one page, not for a site. A short script can pull the cluster for every address from both sources and report the differences. This example reads one sitemap and fetches each page listed in it:

import re, requests, xml.etree.ElementTree as ET

NS = {"s": "http://www.sitemaps.org/schemas/sitemap/0.9",
      "x": "http://www.w3.org/1999/xhtml"}
tree = ET.fromstring(requests.get("https://example.com/sitemap-pages.xml").content)

for url in tree.findall("s:url", NS):
    loc = url.find("s:loc", NS).text
    in_map = {(l.get("hreflang").lower(), l.get("href"))
              for l in url.findall("x:link", NS)}
    page = requests.get(loc).text
    in_html = {(c.lower(), h) for c, h in re.findall(
        r'hreflang="([^"]+)"\s+href="([^"]+)"', page)}
    if in_map != in_html:
        print(loc)
        print("  only in sitemap:", sorted(in_map - in_html))
        print("  only in HTML:   ", sorted(in_html - in_map))

The regular expression assumes hreflang comes before href in each tag; adjust it if your templates write them the other way round. Run it on a sample first, and be gentle with request rates on large sites.

Which source to keep

There is no ranking benefit to either method. Choose the one your team can keep correct with the least effort.

If you keep the HTML, the sitemap still lists your pages; it just drops the xhtml:link entries. If you keep the sitemap, remove the link tags from the templates. Either way, the rule is one source of hreflang, built from the same locale list the site uses for its menus and switcher.

A valid hreflang sitemap, line by line

If the sitemap is the source you keep, it has to be right in every detail. This example covers a contact page in three languages plus a fallback. Every address in the cluster gets its own url entry, and every entry repeats the full set of alternates, including itself:

<?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/contact/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/contact/"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/kontakt/"/>
    <xhtml:link rel="alternate" hreflang="nl" href="https://example.com/nl/contact/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/contact/"/>
  </url>
  <url>
    <loc>https://example.com/de/kontakt/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/contact/"/>
    <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/kontakt/"/>
    <xhtml:link rel="alternate" hreflang="nl" href="https://example.com/nl/contact/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/contact/"/>
  </url>
  <!-- and a third url entry for /nl/contact/ with the same four links -->
</urlset>

• The namespace. Without xmlns:xhtml="http://www.w3.org/1999/xhtml" on the urlset element, the link entries are not understood.
• Full addresses. Every href is absolute, with protocol and host, matching the page's canonical exactly.
• Canonical pages only. Every loc should be a page that is its own canonical, returns 200 and can be indexed.
• Escaping. An ampersand in an address must be written as & in XML, or the file will not parse.
• Size limits. A sitemap can hold up to 50,000 addresses and 50 MB uncompressed. The alternate links count towards the file size, so a site with many locales reaches the size limit well before the address limit. Split into several files under a sitemap index.

Alternate pages can sit in different sitemap files, and even on different hosts if you have verified ownership of each in Search Console, but keeping each cluster together in one file makes it far easier to check.

Generating the sitemap from one locale map

The durable fix is to generate hreflang from the same data the site uses. Here is a minimal generator that takes a mapping of page keys to their address in each locale:

from xml.sax.saxutils import escape

PAGES = {
    "contact": {"en": "https://example.com/contact/",
                "de": "https://example.com/de/kontakt/",
                "nl": "https://example.com/nl/contact/"},
}
DEFAULT = "en"

out = ['<?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">']
for versions in PAGES.values():
    links = [(code, url) for code, url in sorted(versions.items())]
    links.append(("x-default", versions[DEFAULT]))
    for url in versions.values():
        out.append("  <url><loc>%s</loc>" % escape(url))
        for code, href in links:
            out.append('    <xhtml:link rel="alternate" hreflang="%s" href="%s"/>'
                       % (code, escape(href)))
        out.append("  </url>")
out.append("</urlset>")
open("sitemap-pages.xml", "w", encoding="utf-8").write("\n".join(out))

In a real site, PAGES comes from your CMS, database or routing configuration, and pages whose translation is not published are simply absent from their locale's entry. The same mapping should feed the language switcher, so a page cannot appear in one and not the other.

For general sitemap problems unrelated to hreflang, such as entries that return errors, see the guide to sitemap mismatches and oversized sitemaps.

The fix, step by step