Per-Route i18n Routing Strategies

[lucpotage]

Allow i18n.strategy to be defined per-route (via glob patterns), instead of a single global value, so different parts of an app can use different URL/locale routing behavior. Configuration is modeled after Nuxt's [routeRules](https://nuxt.com/docs/4.x/guide/concepts/rendering#hybrid-rendering).

Motivation

Today, strategy is a single global setting applied to every route:

export default defineNuxtConfig({
  i18n: {
    strategy: 'prefix_except_default',
    defaultLocale: 'en'
  }
})

This doesn't fit apps that have both public, SEO-sensitive pages and authenticated/connected areas:

• Public pages (marketing, landing, blog, docs) need localized URLs indexed by search engines. prefix_except_default is the right strategy here: each non-default locale gets its own crawlable, indexable URL (/fr/about), while the default locale stays unprefixed (/about).
• Dashboard / connected pages (behind auth) are not indexed and are typically visited by returning, already-identified users. A prefixed locale in the URL adds no value and just adds noise. no_prefix with automatic locale detection (browser/cookie/user preference) gives a cleaner UX with no impact on SEO, since these routes shouldn't be indexed at all.

Because strategy is global today, you're forced into a single trade-off across the whole app. There is no way to say "SEO-correct prefixing on public routes, prefix-free auto-detected locale on the dashboard" in one config.

Proposal

Widen the type of i18n.strategy itself, rather than introducing new option names. strategy accepts either:

• a string (unchanged): applies that strategy globally, exactly as today.
• an object: keys are glob patterns matched against the route path, values are the strategy to apply to matching routes — same mental model as Nuxt's [routeRules](https://nuxt.com/docs/4.x/guide/concepts/rendering#hybrid-rendering).

There is no separate "default" key. Instead, rule ordering/specificity is what determines the outcome, mirroring how routeRules itself resolves overlapping patterns: a broad catch-all pattern (/**) establishes the baseline, and more specific patterns declared for a subset of routes override it for the routes they match. This keeps the mental model identical to routeRules — no new concepts for readers already familiar with it to learn.

Rules:

• Each key is a glob pattern (same syntax/semantics as routeRules), each value is one of the existing strategy identifiers: no_prefix, prefix, prefix_except_default, prefix_and_default.
• /** acts as the catch-all/default entry — every route matches it, so it's the fallback for anything not covered by a more specific pattern.
• When a route matches multiple patterns, the most specific one wins (deeper/longer segments override broader ones), same resolution order Nitro already applies for routeRules. Declaring /dashboard/** after /** overrides the catch-all for everything under /dashboard.
• If strategy is an object with no /** (or equivalent catch-all) entry, unmatched routes fall back to the module's built-in default (prefix_except_default), same as today when strategy isn't set at all.
• defaultLocale stays a single global setting, independent of strategy. Its role — the canonical/unprefixed locale under prefix_except_default, and the fallback when detection yields nothing under no_prefix — is meaningful the same way no matter which strategy a given route uses, so there's no need for a per-route override.

Config example

export default defineNuxtConfig({
  i18n: {
    defaultLocale: 'en',

    strategy: {
      // Catch-all / default: public, indexable pages get
      // localized URLs per locale, default locale unprefixed — good for SEO
      '/**': 'prefix_except_default',

      // Authenticated / connected app: overrides the catch-all above.
      // No locale in the URL, locale resolved via browser/cookie detection
      '/account/**': 'no_prefix',
      '/login': 'no_prefix',
      '/auth/**': 'no_prefix',

      // API routes are not localized at all
      '/api/**': 'no_prefix'
    }
  }
})

Route matching semantics

• Pattern matching reuses the same glob engine/semantics as Nuxt routeRules for consistency and to avoid teaching a second pattern language.
• Matching should happen at the routing layer so that locale detection, redirects, and generated <link rel="alternate"> SEO tags are computed per matched strategy rather than assuming one strategy app-wide.
• Resolution order follows routeRules: more specific/nested patterns override broader ones regardless of declaration order, so /dashboard/** always overrides /** for routes under /dashboard, and /dashboard/public/** would in turn override /dashboard/** if both are defined.
• No extra conflict-detection layer is added on top: routeRules itself doesn't warn/error on overlapping patterns, it just resolves via the router's matching order, and this proposal mirrors that behavior exactly rather than inventing stricter validation.
• Helpers that build a localized URL (localePath, switchLocalePath, <NuxtLinkLocale>, etc.) already resolve against a target route name/path. They just need to match the glob rules using that destination route rather than the currently active one. This falls out naturally from the matching logic already described above — no separate mechanism needed. So <NuxtLinkLocale :to="{ name: 'index' }"> rendered on a no_prefix dashboard page correctly links to /fr/ (matching index's prefix_except_default rule), and the in-page locale switcher on that same dashboard page correctly stays prefix-free (matching the current route's no_prefix rule) — both cases are just "resolve strategy for route X" applied to different values of X.

Implementation considerations (by Claude Code)

Checked against the current @nuxtjs/i18n source — this is a bigger internal lift than the config change alone suggests, on both the build and runtime sides:

• Build time (src/routing.ts): localizeRoutes currently takes strategy once and applies it to the whole page tree in a single pass. Three things are strategy-driven at that level: shouldLocalizeRoutes decides whether to localize routes at all — for a single-domain no_prefix app, it skips localization entirely, since every locale shares the same unprefixed path; createShouldPrefix decides per route/locale whether to add a locale prefix; resolveDefaultTreeLocales/resolveDefaultLocales compute which locales additionally get an unprefixed "default tree" (needed for prefix_and_default). All three currently read one global strategy value for the entire tree. The walk that builds routes (localizeSingleRoute in src/kit/gen.ts) does carry the full accumulated path per route already, so per-route glob matching is feasible inside createShouldPrefix — but shouldLocalizeRoutes's all-or-nothing skip and the default-tree-locale computation both assume a single strategy for the whole build, and need to become per-route/per-subtree instead of a single upfront decision.
• Runtime: strategy is compiled into the client/server bundle as a literal constant (__I18N_STRATEGY__, set from options.strategy in src/bundler.ts) and read as a flat value in several places: the path matcher (src/runtime/shared/matching.ts), navigation guards (src/runtime/routing/navigation.ts), the composer's public strategy value (src/runtime/plugins/i18n.ts), and the server plugin (src/runtime/server/plugin.ts). Supporting per-route strategy means each of these needs to resolve strategy for the current (or target) route instead of reading one baked-in constant — including composer.strategy, which is a value userland code may currently assume is static for the whole session.
• Net effect: the config API can stay exactly as additive as described above (a string still behaves identically; the object form is new). But under the hood this isn't a small patch — it's a genuine refactor of route generation and several runtime call sites that currently assume one strategy for the entire app. Worth sizing that work explicitly before committing to the config shape.

Backward compatibility

At the config level, this is a type widening of the existing strategy option rather than a new option name, so no migration or deprecation is needed there:

• strategy: 'prefix_except_default' (string) continues to work exactly as today — untouched code path.
• strategy: { '/**': '...', ... } (object) is purely additive; existing configs are unaffected either way.
• No console warnings, no aliasing, no deprecation window required.

[BobbieGoede]

Would disabling i18n routing for those routes through definePageMeta or the pages:extend hook suit your use case as well?

Either like this:

<script setup>
definePageMeta({ i18n: false })
</script>

Or through the hook

export default defineNuxtConfig({
 hooks: {
   'pages:extend'(pages) {
      for (const page of pages) {
        if (/* match dashboard pages */) {
          page.meta ??= {}
          page.meta.i18n = false
        }
      }
    }
  }
})

[lucpotage]

I didn't read this option the correct way. To me it meant disabling i18n on these pages, completely, whereas it only affects the routes, is it right?