I18n

The sitemap module automatically integrates with @nuxtjs/i18n and nuxt-i18n-micro without any extra configuration.

While the integration works out of the box, you may need to fine-tune some options depending on your i18n setup.

I18n Modes

The module supports two main modes for handling internationalized sitemaps:

Automatic I18n Multi Sitemap

The module automatically generates a sitemap for each locale when:

• You're not using the no_prefix strategy
• Or you're using Different Domains

This generates the following structure:

./sitemap_index.xml
./__sitemap__/en-US.xml
./__sitemap__/fr-FR.xml
# ...additional locales

Each locale sitemap takes the locale's language as its name. If a locale has no language, the sitemap takes the locale code, for example /__sitemap__/en.xml. The sitemapsPathPrefix option sets the /__sitemap__/ part.

Key features:

• Includes app sources automatically
• The nuxt:pages source determines the correct alternatives for your pages
• To disable app sources, set excludeAppSources: true

Custom sitemaps with I18n. You can add custom sitemaps alongside the automatic i18n multi-sitemap. When any sitemap uses includeAppSources: true, the module still generates per-locale sitemaps and merges the exclude/include filters:

export default defineNuxtConfig({
  sitemap: {
    sitemaps: {
      pages: {
        includeAppSources: true,
        exclude: ['/admin/**'],
      },
      posts: {
        sources: ['/api/__sitemap__/posts'],
      }
    }
  }
})

This generates:

./sitemap_index.xml
./__sitemap__/en-US-pages.xml   # locale sitemap with /admin/** excluded
./__sitemap__/fr-FR-pages.xml   # locale sitemap with /admin/** excluded
./__sitemap__/posts.xml         # custom sitemap (kept as-is)

The sitemap name is preserved with the format {language}-{name}, or {code}-{name} for a locale without language. Sitemaps without includeAppSources (like posts) remain as separate sitemaps.

I18n Pages Mode

When you enable i18n.pages in your i18n configuration, the sitemap module generates a single sitemap using that configuration.

Key differences:

• Does not include app sources automatically
• You can add additional URLs using the sources option

Dynamic URLs with i18n

By default, dynamic URLs you provide won't have i18n data and will only appear in the default locale sitemap.

To handle i18n for dynamic URLs, use these special options:

1. _i18nTransform - Automatic Locale Transformation

Use _i18nTransform: true to automatically generate URLs for all locales:

export default defineSitemapEventHandler(() => {
  return [
    {
      loc: '/about-us',
      // automatically creates: /en/about-us, /fr/about-us, etc.
      _i18nTransform: true,
    }
  ]
})

Custom path translations. If you have custom path translations defined in your i18n configuration using pages, the _i18nTransform option will automatically use them:

export default defineNuxtConfig({
  i18n: {
    pages: {
      about: {
        en: '/about',
        fr: '/a-propos',
        es: '/acerca-de',
      },
      services: {
        en: '/services',
        fr: '/offres',
        es: '/servicios',
      },
    },
  },
})

With this configuration, when you set _i18nTransform: true on a URL:

export default defineSitemapEventHandler(() => {
  return [
    {
      loc: '/about', // base path
      _i18nTransform: true,
      // automatically generates:
      // - /about (for en)
      // - /fr/a-propos (for fr)
      // - /es/acerca-de (for es)
    }
  ]
})

2. _sitemap - Specific Locale Assignment

Use _sitemap to assign a URL to a specific locale sitemap. The value is the locale sitemap name: the locale's language, or its code if it has no language.

export default defineSitemapEventHandler(() => {
  return [
    {
      loc: '/about-us',
      // only appears in the English sitemap, /__sitemap__/en-US.xml
      _sitemap: 'en-US',
    }
  ]
})

If _sitemap names no sitemap, the module logs an error and omits the URL.

Debugging Hreflang

By default, hreflang tags aren't visible in the XML stylesheet view. To see them, you'll need to view the page source.

Note: Search engines can still see these tags even if they're not visible in the stylesheet.

To display hreflang tag counts in the visual interface, customize the columns:

export default defineNuxtConfig({
  sitemap: {
    xslColumns: [
      { label: 'URL', width: '50%' },
      { label: 'Last Modified', select: 'sitemap:lastmod', width: '25%' },
      { label: 'Hreflangs', select: 'count(xhtml:link)', width: '25%' },
    ],
  }
})

For more customization options, see the Customizing UI guide.

Opting Out of I18n Integration

If you're using @nuxtjs/i18n or nuxt-i18n-micro but want the sitemap module to ignore it entirely, set autoI18n: false. This generates a single sitemap without locale prefixes or hreflang tags.

export default defineNuxtConfig({
  sitemap: {
    autoI18n: false,
  },
})