Excluding Static Files from i18n Routing

Overview

By default, nuxt-i18n-micro automatically excludes common static files from i18n routing processing. However, you can also configure custom exclusion patterns to prevent specific paths from being processed by the i18n system.

Built-in Exclusions

The module automatically excludes the following file types and patterns:

• Sitemaps: /sitemap*.xml, /sitemap-en.xml, etc.
• SEO files: /robots.txt, /favicon.ico
• PWA files: /manifest.json, /sw.js, /workbox-*.js
• Static assets: Files with extensions like .xml, .txt, .ico, .json, .js, .css, .png, .jpg, .jpeg, .gif, .svg, .woff, .woff2, .ttf, .eot
• Internal Nuxt paths: Any path starting with __ (like /__nuxt/)

Custom Exclusion Patterns

You can define custom exclusion patterns using the excludePatterns option:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-i18n-micro'],

  i18n: {
    locales: [
      { code: 'en', iso: 'en-US' },
      { code: 'it', iso: 'it-IT' },
    ],
    defaultLocale: 'en',

    // Custom exclusion patterns
    excludePatterns: [
      // String patterns (exact match or prefix)
      '/api/health',
      '/admin',

      // String patterns with wildcards
      '/api/*',
      '/admin/**',

      // Regular expressions
      /^\/api\/v\d+\//,
      /\.(pdf|doc|docx)$/,
    ],
  },
})

Pattern Types

String Patterns

• Exact match: '/api/health' - matches exactly /api/health
• Prefix match: '/admin' - matches /admin and /admin/dashboard
• Wildcards: '/api/*' - matches /api/users but not /api/users/123
• Deep wildcards: '/admin/**' - matches /admin/users and /admin/users/123

Regular Expressions

Use RegExp objects for complex pattern matching:

excludePatterns: [
  /^\/api\/v\d+\//, // API versioned routes
  /\.(pdf|doc|docx)$/, // Document files
  /^\/static\//, // Static directory
  /^\/[a-z]{2}\/api\//, // Localized API routes
]

Use Cases

SEO Files

excludePatterns: ['/sitemap.xml', '/sitemap-*.xml', '/robots.txt', '/favicon.ico']

API Routes

excludePatterns: ['/api/**', '/graphql', '/webhook/**']

Admin Panels

excludePatterns: ['/admin', '/admin/**', '/dashboard']

Static Assets

excludePatterns: ['/assets/**', '/static/**', '/uploads/**']

How It Works

1. Server Middleware: A Nitro middleware runs first to check exclusion patterns
2. Page Processing: During page resolution, excluded paths are skipped
3. Catch-all Route: The fallback route checks exclusions before processing
4. Prerendering: Excluded paths are not included in prerendered routes

Performance Impact

• Exclusion checks are optimized and run early in the request lifecycle
• Built-in patterns use efficient regex matching
• Custom patterns are cached and reused
• Minimal performance overhead for excluded paths

Troubleshooting

Static Files Still Being Intercepted

1. Check pattern syntax: Ensure your patterns match the exact path structure
2. Use regex for complex patterns: String wildcards have limitations
3. Test patterns: Use browser dev tools to verify the actual request path
4. Check order: Ensure exclusion patterns are defined before other i18n config

Pattern Not Working

// ❌ Wrong - this won't work
excludePatterns: ['sitemap.xml']

// ✅ Correct - include leading slash
excludePatterns: ['/sitemap.xml']

// ✅ Better - use regex for flexibility
excludePatterns: [/^\/sitemap.*\.xml$/]

Debug Mode

Enable debug mode to see exclusion processing:

i18n: {
  debug: true,
  excludePatterns: ['/api/**']
}

This will log exclusion decisions in the console.

Migration from Workarounds

If you were using workarounds like route rules or middleware, you can now replace them with excludePatterns:

// ❌ Old workaround
export default defineNuxtConfig({
  routeRules: {
    '/sitemap*.xml': { headers: { 'content-type': 'application/xml' } },
  },
})

// ✅ New approach
export default defineNuxtConfig({
  i18n: {
    excludePatterns: ['/sitemap*.xml'],
  },
})

The new approach is more reliable and works at multiple levels of the routing system.