feat: add support for localizations in sitemap generator

Author: ctkc

docs/02-app/02-api-reference/02-file-conventions/01-metadata/sitemap.mdx

@@ -87,12 +87,99 @@ Output:
 </urlset>
 ```
 
+### Generate a localized Sitemap
+
+```ts filename="app/sitemap.ts" switcher
+import { MetadataRoute } from 'next'
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  return [
+    {
+      url: 'https://acme.com',
+      lastModified: new Date(),
+      alternates: {
+        languages: {
+          es: 'https://acme.com/es',
+          de: 'https://acme.com/de',
+        },
+      },
+    },
+    {
+      url: 'https://acme.com/about',
+      lastModified: new Date(),
+      alternates: {
+        languages: {
+          es: 'https://acme.com/es/about',
+          de: 'https://acme.com/de/about',
+        },
+      },
+    },
+    {
+      url: 'https://acme.com/blog',
+      lastModified: new Date(),
+      alternates: {
+        languages: {
+          es: 'https://acme.com/es/blog',
+          de: 'https://acme.com/de/blog',
+        },
+      },
+    },
+  ]
+}
+```
+
+Output:
+
+```xml filename="acme.com/sitemap.xml"
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9 xmlns:xhtml="http://www.w3.org/1999/xhtml"">
+  <url>
+    <loc>https://acme.com</loc>
+    <xhtml:link
+      rel="alternate"
+      hreflang="es"
+      href="https://acme.com/es"/>
+    <xhtml:link
+      rel="alternate"
+      hreflang="de"
+      href="https://acme.com/de"/>
+    <lastmod>2023-04-06T15:02:24.021Z</lastmod>
+  </url>
+  <url>
+    <loc>https://acme.com/about</loc>
+    <xhtml:link
+      rel="alternate"
+      hreflang="es"
+      href="https://acme.com/es/about"/>
+    <xhtml:link
+      rel="alternate"
+      hreflang="de"
+      href="https://acme.com/de/about"/>
+    <lastmod>2023-04-06T15:02:24.021Z</lastmod>
+  </url>
+  <url>
+    <loc>https://acme.com/blog</loc>
+    <xhtml:link
+      rel="alternate"
+      hreflang="es"
+      href="https://acme.com/es/blog"/>
+    <xhtml:link
+      rel="alternate"
+      hreflang="de"
+      href="https://acme.com/de/blog"/>
+    <lastmod>2023-04-06T15:02:24.021Z</lastmod>
+  </url>
+</urlset>
+```
+
 ### Sitemap Return Type
 
 ```tsx
 type Sitemap = Array<{
   url: string
   lastModified?: string | Date
+  alternates?: {
+    languages?: Languages<string>
+  }
 }>
 ```
 

packages/next/src/build/webpack/loaders/metadata/resolve-route-data.test.ts

@@ -95,5 +95,32 @@ describe('resolveRouteData', () => {
         "
       `)
     })
+    it('should resolve sitemap.xml with alternates', () => {
+      expect(
+        resolveSitemap([
+          {
+            url: 'https://example.com',
+            lastModified: '2021-01-01',
+            alternates: {
+              languages: {
+                es: 'https://example.com/es',
+                de: 'https://example.com/de',
+              },
+            },
+          },
+        ])
+      ).toMatchInlineSnapshot(`
+          "<?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</loc>
+          <xhtml:link rel=\\"alternate\\" hreflang=\\"es\\" href=\\"https://example.com/es\\" />
+          <xhtml:link rel=\\"alternate\\" hreflang=\\"de\\" href=\\"https://example.com/de\\" />
+          <lastmod>2021-01-01</lastmod>
+          </url>
+          </urlset>
+          "
+      `)
+    })
   })
 })

packages/next/src/build/webpack/loaders/metadata/resolve-route-data.ts

@@ -1,5 +1,6 @@
 import type { MetadataRoute } from '../../../../lib/metadata/types/metadata-interface'
 import { resolveArray } from '../../../../lib/metadata/generate/utils'
+import { Languages } from '../../../../lib/metadata/types/alternative-urls-types'
 
 // convert robots data to txt string
 export function resolveRobots(data: MetadataRoute.Robots): string {
@@ -44,12 +45,31 @@ export function resolveRobots(data: MetadataRoute.Robots): string {
 // TODO-METADATA: support multi sitemap files
 // convert sitemap data to xml string
 export function resolveSitemap(data: MetadataRoute.Sitemap): string {
+  const hasAlternates = data.some(
+    (item) => Object.keys(item.alternates ?? {}).length > 0
+  )
+
   let content = ''
   content += '<?xml version="1.0" encoding="UTF-8"?>\n'
-  content += '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
+  content += '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"'
+  if (hasAlternates) {
+    content += ' xmlns:xhtml="http://www.w3.org/1999/xhtml">\n'
+  } else {
+    content += '>\n'
+  }
   for (const item of data) {
     content += '<url>\n'
     content += `<loc>${item.url}</loc>\n`
+    if (
+      item.alternates?.languages &&
+      Object.keys(item.alternates.languages).length
+    ) {
+      for (const language in item.alternates.languages) {
+        content += `<xhtml:link rel="alternate" hreflang="${language}" href="${
+          item.alternates.languages[language as keyof Languages<string>]
+        }" />\n`
+      }
+    }
     if (item.lastModified) {
       content += `<lastmod>${
         item.lastModified instanceof Date

packages/next/src/lib/metadata/types/alternative-urls-types.ts

@@ -426,7 +426,7 @@ type UnmatchedLang = 'x-default'
 
 type HrefLang = LangCode | UnmatchedLang
 
-type Languages<T> = {
+export type Languages<T> = {
   [s in HrefLang]?: T
 }
 

packages/next/src/lib/metadata/types/metadata-interface.ts

@@ -1,5 +1,6 @@
 import type {
   AlternateURLs,
+  Languages,
   ResolvedAlternateURLs,
 } from './alternative-urls-types'
 import type {
@@ -558,6 +559,9 @@ type RobotsFile = {
 type SitemapFile = Array<{
   url: string
   lastModified?: string | Date
+  alternates?: {
+    languages?: Languages<string>
+  }
 }>
 
 type ResolvingMetadata = Promise<ResolvedMetadata>

test/e2e/app-dir/metadata-dynamic-routes/app/sitemap.ts

@@ -10,6 +10,12 @@ export default function sitemap(): MetadataRoute.Sitemap {
     {
       url: 'https://example.com/about',
       lastModified: '2021-01-01',
+      alternates: {
+        languages: {
+          es: 'https://example.com/es/about',
+          de: 'https://example.com/de/about',
+        },
+      },
     },
   ]
 }