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 correctalternatives
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:
_i18nTransform
- Automatic Locale Transformation 1.
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)
}
]
})
_sitemap
- Specific Locale Assignment 2.
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.