Sitemaps guide
How to add hreflang to an XML sitemap
Build complete alternate-language clusters with xhtml:link, self-references, reciprocal links, and absolute canonical URLs.
8 min read · Updated 2026-08-21
The short answer
Add one xhtml:link for every language variant to every URL in the cluster, including the page itself. Declare the XHTML namespace, use absolute URLs, keep the same reciprocal set on each variant, and use x-default only for a genuine fallback page.Think in complete clusters
Hreflang is not a one-way annotation. If the English URL names the Polish alternate, the Polish URL must name the English alternate and itself. A cluster is complete only when every member publishes the same set.
- Include a self-reference for each URL.
- Include every other language or region variant.
- Use canonical, indexable, successful URLs.
- Keep language codes and region codes in their standard forms.
Declare and use the XHTML extension
The alternate element belongs to XHTML, not the sitemap namespace. The xhtml prefix is conventional; the namespace URI is what gives the element its identity.
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://example.com/en/pricing</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing"/>
<xhtml:link rel="alternate" hreflang="pl" href="https://example.com/pl/cennik"/>
</url>
<url>
<loc>https://example.com/pl/cennik</loc>
<xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/pricing"/>
<xhtml:link rel="alternate" hreflang="pl" href="https://example.com/pl/cennik"/>
</url>
</urlset>Validate relationships, not just syntax
A document can be perfectly well-formed while its clusters are incomplete. Group entries by destination set and compare them: each member should expose the same hreflang-to-URL mapping, and every destination should appear as its own loc somewhere in the submitted sitemap set.
Prove the fix
- Validate the sitemapCheck XML, root shape, loc values, and extension placement.
- Explore every alternate pathConfirm the xhtml namespace is present on extracted paths.
- Review namespace behaviorUnderstand why unprefixed XPath names miss sitemap elements.
Related guides
- Why XPath matches nothing in a default namespaceThe XPath 1.0 namespace rule behind an empty //loc result, with the prefix-bound solution and the local-name fallback.
- How to fix “Sitemap could not be read”A deterministic checklist for separating fetch failures, HTTP problems, malformed XML, namespace mistakes, and invalid sitemap entries.
Get started
Bring order to the XML your team can't afford to ignore.
Create a free account and get a private workspace to search, validate, diff, and monitor your XML feeds, sitemaps, schemas, and vendor integrations.