Sitemaps omit hreflang self/x-default alternates for untranslated entries on i18n sites

[khoinguyenpham04]

This Roadmap discussion mirrors #1522: Sitemaps omit hreflang self/x-default alternates for untranslated entries on i18n sites.

Use this discussion to upvote the roadmap item and discuss priority, use cases, and product feedback. Keep implementation tracking, reproduction details, and PR-specific feedback on the source issue.

• Source issue: #1522
• Status: Closed
• Labels: bug, triage/failed, bot:bug, bot:failed
• Original author: diogoascarneiro

Original Issue

Description

On an EmDash site with i18n enabled, generated collection sitemaps only emit <xhtml:link rel="alternate"> entries when a content item has more than one translated sibling.

For a published default-locale post with no localized versions, the generated sitemap currently emits:

<url>
  <loc>https://example.invalid/example-post</loc>
  <lastmod>2026-01-01T00:00:00.000Z</lastmod>
</url>

Expected output when i18n is enabled:

<url>
  <loc>https://example.invalid/example-post</loc>
  <lastmod>2026-01-01T00:00:00.000Z</lastmod>
  <xhtml:link rel="alternate" hreflang="en-us" href="https://example.invalid/example-post" />
  <xhtml:link rel="alternate" hreflang="x-default" href="https://example.invalid/example-post" />
</url>

This matters because Google’s hreflang sitemap guidance says each URL should list every language/locale variant, including itself. For single-locale entries on a multilingual site, the entry itself is still the locale-specific version and should be declared as such. x-default also gives crawlers a clear fallback URL.

References:

• Google Search Central: “Each language version must list itself as well as all other language versions” and sitemap hreflang entries should include every alternate, including itself: https://developers.google.com/search/docs/specialty/international/localized-versions
• Sitemaps protocol: sitemaps are a crawler discovery mechanism and XML values must be valid/escaped: https://www.sitemaps.org/protocol.html
• Cloudflare AI Search: AI Search supports automated/web indexing and language metadata filtering. Consistent locale annotations improve compatibility for multilingual content discovery and downstream indexing/filtering workflows: https://developers.cloudflare.com/ai-search/

Steps to reproduce

1. Configure an Astro + EmDash site with multiple locales, for example en-us as the default locale and at least one non-default locale.

export default defineConfig({
  i18n: {
    defaultLocale: "en-us",
    locales: ["en-us", "fr-fr"],
    routing: {
      prefixDefaultLocale: false,
    },
  },
  integrations: [
    emdash({
      i18n: {
        defaultLocale: "en-us",
        locales: ["en-us", "fr-fr"],
      },
    }),
  ],
});

2. Create an SEO-enabled collection with a URL pattern.

{
  "slug": "posts",
  "label": "Posts",
  "labelSingular": "Post",
  "urlPattern": "/{slug}/",
  "hasSeo": true,
  "supports": ["drafts", "revisions", "preview"]
}

3. Publish one default-locale post, for example locale en-us, with no translated sibling entries.

4. Request the generated collection sitemap, for example:

https://example.invalid/sitemap-posts.xml

5. Observe that the <url> entry only includes <loc> and <lastmod>, with no self hreflang and no x-default.

Environment

• emdash version: 0.20.0
• Node.js version: not version-specific
• Runtime: Cloudflare Workers
• OS: macOS

Logs / error output

No runtime error is thrown. The issue appears to come from the sitemap route logic.

In src/astro/routes/sitemap-[collection].xml.ts, alternates are only written when there is more than one sibling:

if (useXhtml && siblings && siblings.length > 1) {
  // emits xhtml:link alternates
}

Ungrouped entries are emitted with siblings as null:

for (const entry of ungrouped) {
  await writeUrl(entry, null);
}

As a result, untranslated entries on i18n-enabled sites never get their locale self-reference or x-default fallback in the sitemap.