I18n

Introduction

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
• And you haven't manually configured the sitemaps option

This generates the following structure:

./sitemap_index.xml
./en-sitemap.xml
./fr-sitemap.xml
# ...additional locales

Key features:

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

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:

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

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)', width: '25%' },
    ],
  }
})

For more customization options, see the Customising UI guide.