---
title: "I18n"
description: "Setting up a sitemap with Nuxt I18n and Nuxt I18n Micro."
canonical_url: "https://nuxtseo.com/docs/sitemap/guides/i18n"
last_updated: "2026-05-12T13:38:34.915Z"
---

## Introduction

The sitemap module automatically integrates with [@nuxtjs/i18n](https://i18n.nuxtjs.org/) and [nuxt-i18n-micro](https://github.com/s00d/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](https://i18n.nuxtjs.org/docs/v7/different-domains)

This generates the following structure:

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

Key features:

- Includes [app sources](/docs/sitemap/getting-started/data-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:

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

This generates:

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

The sitemap name is preserved with the format `{locale}-{name}`. 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](/docs/sitemap/getting-started/data-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:

```ts [server/api/__sitemap__/urls.ts]
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:

```ts [nuxt.config.ts]
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:

```ts [server/api/__sitemap__/urls.ts]
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:

```ts [server/api/__sitemap__/urls.ts]
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:

```ts
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 [Customising UI guide](/docs/sitemap/advanced/customising-ui).

## 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.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  sitemap: {
    autoI18n: false,
  },
})
```