feat(page-manager): add support for custom exclusion patterns in i18n

Author: s00d

src/module.ts

@@ -106,6 +106,7 @@ export default defineNuxtModule<ModuleOptions>({
       return selectedForm.trim().replace('{count}', count.toString())
     },
     customRegexMatcher: undefined,
+    excludePatterns: undefined,
   },
   async setup(options, nuxt) {
     const defaultLocale = process.env.DEFAULT_LOCALE ?? options.defaultLocale ?? 'en'
@@ -130,7 +131,7 @@ export default defineNuxtModule<ModuleOptions>({
     const rootDirs = nuxt.options._layers.map(layer => layer.config.rootDir).reverse()
 
     const localeManager = new LocaleManager(options, rootDirs)
-    const pageManager = new PageManager(localeManager.locales, defaultLocale, options.strategy!, options.globalLocaleRoutes, options.noPrefixRedirect!)
+    const pageManager = new PageManager(localeManager.locales, defaultLocale, options.strategy!, options.globalLocaleRoutes, options.noPrefixRedirect!, options.excludePatterns)
 
     addTemplate({
       filename: 'i18n.plural.mjs',
@@ -158,6 +159,7 @@ export default defineNuxtModule<ModuleOptions>({
       isSSG: isSSG,
       disablePageLocales: options.disablePageLocales ?? false,
       canonicalQueryWhitelist: options.canonicalQueryWhitelist ?? [],
+      excludePatterns: options.excludePatterns ?? [],
     }
 
     // if there is a customRegexMatcher set and all locales don't match the custom matcher, throw error
@@ -294,7 +296,7 @@ export default defineNuxtModule<ModuleOptions>({
             const fullPath = path.posix.normalize(`${parentPath}/${page.path}`) // Combine parent path and current path
 
             // Skip internal paths
-            if (isInternalPath(fullPath)) {
+            if (isInternalPath(fullPath, options.excludePatterns)) {
               return
             }
 
@@ -328,15 +330,15 @@ export default defineNuxtModule<ModuleOptions>({
                   }
 
                   // Add localized path to array
-                  if (!isInternalPath(localizedPath)) {
+                  if (!isInternalPath(localizedPath, options.excludePatterns)) {
                     prerenderRoutes.push(localizedPath)
                   }
                 }
               })
             }
             else {
               // If there's no dynamic locale segment in the path, just add it to the array
-              if (!isInternalPath(fullPath)) {
+              if (!isInternalPath(fullPath, options.excludePatterns)) {
                 prerenderRoutes.push(fullPath)
               }
             }
@@ -514,7 +516,7 @@ export default defineNuxtModule<ModuleOptions>({
       // Remove internal paths before localization processing
       const routesToRemove: string[] = []
       routesSet.forEach((route) => {
-        if (isInternalPath(route)) {
+        if (isInternalPath(route, options.excludePatterns)) {
           routesToRemove.push(route)
         }
       })
@@ -525,7 +527,7 @@ export default defineNuxtModule<ModuleOptions>({
 
       // Go through each existing route and add localized versions
       routesSet.forEach((route) => {
-        if (!/\.[a-z0-9]+$/i.test(route) && !isInternalPath(route)) {
+        if (!/\.[a-z0-9]+$/i.test(route) && !isInternalPath(route, options.excludePatterns)) {
           localeManager.locales!.forEach((locale) => {
             // For prefix and prefix_and_default strategies generate routes for defaultLocale too
             // For prefix_except_default strategy skip defaultLocale

src/page-manager.ts

@@ -29,12 +29,14 @@ export class PageManager {
   activeLocaleCodes: string[]
   globalLocaleRoutes: Record<string, Record<string, string> | false | boolean>
   noPrefixRedirect: boolean
+  excludePatterns: (string | RegExp)[] | undefined
 
-  constructor(locales: Locale[], defaultLocaleCode: string, strategy: Strategies, globalLocaleRoutes: GlobalLocaleRoutes, noPrefixRedirect: boolean) {
+  constructor(locales: Locale[], defaultLocaleCode: string, strategy: Strategies, globalLocaleRoutes: GlobalLocaleRoutes, noPrefixRedirect: boolean, excludePatterns?: (string | RegExp)[]) {
     this.locales = locales
     this.defaultLocale = this.findLocaleByCode(defaultLocaleCode) || { code: defaultLocaleCode }
     this.strategy = strategy
     this.noPrefixRedirect = noPrefixRedirect
+    this.excludePatterns = excludePatterns
     this.activeLocaleCodes = this.computeActiveLocaleCodes()
     this.globalLocaleRoutes = globalLocaleRoutes || {}
   }
@@ -62,7 +64,7 @@ export class PageManager {
 
     for (const page of [...pages]) {
       // Skip internal paths during page processing
-      if (page.path && isInternalPath(page.path)) {
+      if (page.path && isInternalPath(page.path, this.excludePatterns)) {
         continue
       }
 
@@ -98,7 +100,7 @@ export class PageManager {
         const pageName = page.name ?? ''
 
         // Skip removal for internal paths
-        if (isInternalPath(pagePath)) continue
+        if (isInternalPath(pagePath, this.excludePatterns)) continue
 
         if (this.globalLocaleRoutes[pageName] === false) continue
 

src/runtime/components/locale-redirect.vue

@@ -3,16 +3,28 @@
 </template>
 
 <script setup>
-import { useRoute, useI18n, createError, navigateTo } from '#imports'
+import { useRoute, useI18n, createError, navigateTo, useRuntimeConfig } from '#imports'
+import { isInternalPath } from '../../utils'
 
 const route = useRoute()
 const { $getLocales, $defaultLocale } = useI18n()
+const config = useRuntimeConfig()
 
 const locales = $getLocales().map(locale => locale.code)
 const defaultLocale = $defaultLocale() || 'en'
 const pathSegments = route.fullPath.split('/')
 const firstSegment = pathSegments[1]
 
+// Check if this path should be excluded from i18n processing
+const excludePatterns = config.public.i18nConfig?.excludePatterns
+if (isInternalPath(route.fullPath, excludePatterns)) {
+  // This is a static file or excluded path, let Nuxt handle it normally
+  throw createError({
+    statusCode: 404,
+    statusMessage: 'Static file - should not be processed by i18n',
+  })
+}
+
 const generateRouteName = (segments) => {
   return segments
     .slice(1)

src/utils.ts

@@ -2,7 +2,66 @@ import path from 'node:path'
 import type { NuxtPage } from '@nuxt/schema'
 import type { Locale, LocaleCode } from 'nuxt-i18n-micro-types'
 
-export const isInternalPath = (p: string) => /(?:^|\/)__[^/]+/.test(p)
+/**
+ * Default patterns for static files that should be excluded from i18n routing
+ */
+const DEFAULT_STATIC_PATTERNS = [
+  /^\/sitemap.*\.xml$/,
+  /^\/sitemap\.xml$/,
+  /^\/robots\.txt$/,
+  /^\/favicon\.ico$/,
+  /^\/apple-touch-icon.*\.png$/,
+  /^\/manifest\.json$/,
+  /^\/sw\.js$/,
+  /^\/workbox-.*\.js$/,
+  /\.(xml|txt|ico|json|js|css|png|jpg|jpeg|gif|svg|woff|woff2|ttf|eot)$/,
+]
+
+/**
+ * Checks if a path should be excluded from i18n routing
+ * @param path - The path to check
+ * @param excludePatterns - Optional custom exclusion patterns
+ * @returns true if the path should be excluded
+ */
+export const isInternalPath = (path: string, excludePatterns?: (string | RegExp | object)[]): boolean => {
+  // Check internal Nuxt paths (existing behavior)
+  if (/(?:^|\/)__[^/]+/.test(path)) {
+    return true
+  }
+
+  // Check default static file patterns
+  for (const pattern of DEFAULT_STATIC_PATTERNS) {
+    if (pattern.test(path)) {
+      return true
+    }
+  }
+
+  // Check custom exclusion patterns
+  if (excludePatterns) {
+    for (const pattern of excludePatterns) {
+      if (typeof pattern === 'string') {
+        // Convert string to regex if it contains wildcards or is a simple match
+        if (pattern.includes('*') || pattern.includes('?')) {
+          const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'))
+          if (regex.test(path)) {
+            return true
+          }
+        }
+        else if (path === pattern || path.startsWith(pattern)) {
+          return true
+        }
+      }
+      else if (pattern instanceof RegExp) {
+        if (pattern.test(path)) {
+          return true
+        }
+      }
+      // Skip empty objects or other types
+    }
+  }
+
+  return false
+}
 
 export function extractLocaleRoutes(content: string, filePath: string): Record<string, string> | null {
   // Look for defineI18nRoute call (with or without dollar sign)