Add the sitemap namespace 'xmlns:xhtml="http://www.w3.org/1999/xhtml"' to the root <urlset> element
For each URL, include one <xhtml:link rel="alternate" hreflang="{lang-code}" href="{url}"/> tag per language/region variant inside the <url> block, plus one pointing back to itself
Add an x-default variant using hreflang="x-default" pointing to the URL that should be shown when no other language/region matches the user — typically a language selector or the global homepage
Ensure full reciprocity: every URL referenced in a hreflang annotation must itself contain a hreflang set pointing back to all variants including the page that references it
Validate language codes using ISO 639-1 for language (e.g., 'en', 'fr') and optionally ISO 3166-1 alpha-2 for region (e.g., 'en-US', 'fr-FR'); do not use BCP 47 variants not supported by Google
Crawl and validate the sitemap using a tool such as Screaming Frog or hreflang.org validator to detect missing return links, incorrect codes, and canonical conflicts before submission
Known gotchas
Missing reciprocal links are the most common hreflang failure — if page A references page B in hreflang, page B must reference page A back, otherwise Google may ignore the entire cluster
x-default does not mean 'default language for all unmatched users in all regions' — it is specifically a fallback for users whose language/region matches no other hreflang value; misusing it as a site-wide default can cause incorrect language targeting
Hreflang annotations in sitemaps and in HTML <link> tags can coexist for the same site, but mixing them on the same page for different URL sets creates conflicts that Google may resolve inconsistently
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp