v3.0.0

Date: 2026-02-04

Version: v3.0.0

We're announcing v3.0.0 with a major architectural overhaul: complete rewrite of the translation storage system for maximum performance, route generation and runtime path logic are now split into dedicated packages, and the redirect flow has been redesigned for better reliability and Serverless compatibility.

What's New?

Performance Optimization — New Translation Storage Architecture

The translation loading and caching system has been completely rewritten for maximum performance:

• Centralized TranslationStorage class — A new TranslationStorage class (src/runtime/utils/storage.ts) provides a unified storage for both client and server. Uses globalThis with Symbol.for to guarantee a true singleton across the entire Node.js process, preventing cache duplication across bundled modules.
• Optimized $t() function (tFast) — The translation function uses a direct lookup against a single active dictionary:
  1. All translations (root + page-specific + fallback) are pre-merged at build time into a single file per page
  2. On same-locale navigation, new page translations are cumulatively merged into the active dictionary (prevents key flickering during transition animations)
  3. Supports nested keys (key.subkey.subsubkey) with optimized path resolution
  4. No Map lookups or locale/route calculations on each call — uses pre-computed context
• Server-side injection via window.__I18N__ — Translations loaded during SSR are injected into the HTML as a script tag. The client reads directly from window.__I18N__ on initial load, avoiding duplicate fetches.
• Local chunk cache in plugin — The plugin maintains a local loadedChunks Map that stores all loaded translation chunks. Once loaded, translations are never re-fetched during the page lifecycle.
• Build-time pre-merge — A preMergeLocales step in module.ts merges all layers, fallback locale chains, and root-level translations into every page file at build time. The server-loader simply reads a single pre-built file — no runtime merging needed.

Performance improvements:

• Reduced memory allocation per request (no object re-creation on each $t() call)
• Lower garbage collection pressure
• Faster response times under load
• Stable memory usage pattern (no "jumping" graphs)

Route & Path Strategy Packages

• @i18n-micro/route-strategy — Build-time route generation: extends Nuxt pages with localized routes, handles aliases, nested routes, and custom paths per strategy. Single entry point: new RouteGenerator(options) and extendPages(pages). Strategies (no_prefix, prefix, prefix_except_default, prefix_and_default) are implemented as separate classes and selected via a factory.
• @i18n-micro/path-strategy — Runtime path and locale handling: provides PathStrategy for building localized paths, resolving redirects, and locale switching. Tree-shakeable subpath exports (/prefix, /no-prefix, etc.) so only the selected strategy is bundled. Uses pure functions for route resolution and pre-computed context flags for minimal allocations.
• Structured package layout — Route logic in @i18n-micro/route-strategy with core/, strategies/. Path strategy in @i18n-micro/path-strategy with a flat src/ structure: types.ts, path.ts, resolver.ts, helpers.ts, and strategies/.
• Consistent behavior — Alias handling, parent–child path joining, custom globalLocaleRoutes / filesLocaleRoutes / routeLocales, and immutability guarantees are covered by a dedicated test suite.

Redirect Architecture Overhaul

• Server middleware — Redirects and 404 handling run in Nitro middleware (i18n.global.ts). This executes before Nuxt render, so redirects from / to /<locale>/ happen without an error flash when a locale cookie is present.
• Client plugin (client-side) — A client-only plugin (06.client-redirect.client.ts) runs after hydration and handles redirects when useI18nLocale() or cookie sets a non-default locale. Nitro runs before Nuxt, so the server cannot see cookie/state changes from user plugins; the client plugin covers this case.
• No fallback component — The locale-redirect.vue fallback component and fallbackRedirectComponentPath option have been removed. Redirect logic is fully handled by the server middleware and client plugin.
• Custom path support — Paths like /kontakt for German (via globalLocaleRoutes) are correctly recognized as valid without a locale prefix, avoiding incorrect 404s during prerender.
• customRegexMatcher fix — When using customRegexMatcher, the pattern now matches the entire first path segment (with ^ and $ anchors). This prevents false 404s for routes like /locale-test when the pattern [a-z]{2}-[a-z]{2} would previously match substrings.
• autoDetectPath fix — The autoDetectPath option now correctly compares against the original URL path, preventing unwanted redirects when explicitly navigating to locale-prefixed URLs.

useI18nLocale Composable

• Centralized locale management — New useI18nLocale() composable replaces useLocaleCookies and provides a single entry point for locale state, cookies, and sync utilities.
• API — locale, localeCookie, hashCookie, getLocale(), getPreferredLocale(), setLocale(), syncLocale(), isValidLocale(), getEffectiveLocale(), resolveInitialLocale().
• Programmatic locale — Use useI18nLocale().setLocale(locale) in server plugins instead of useState('i18n-locale') for cleaner, centralized locale handling.

Custom Auto-Detection & Configuration

• getI18nConfig() — Custom plugins (e.g. for locale detection) should use getI18nConfig() from #build/i18n.strategy.mjs instead of useRuntimeConfig().public.i18nConfig. This provides direct access to the resolved i18n config (e.g. localeCookie) without relying on runtime config.
• Cookie name — Use getI18nConfig().localeCookie ?? 'user-locale' when implementing custom detection logic.

Simplified Integration Packages

All integration packages (@i18n-micro/vue, @i18n-micro/astro, @i18n-micro/node, @i18n-micro/react, @i18n-micro/preact, @i18n-micro/solid) have been simplified and optimized, sharing the same core translation logic.

Configuration Changes

• previousPageFallback removed — This option is no longer needed. The new cumulative merge strategy automatically keeps previous page translations available during transition animations, then cleans them up via the page:transition:finish hook.
• hmr — Moved from experimental.hmr to a top-level option. Controls server-side HMR for translation files (enabled by default in development).

// Before (v2.x)
export default defineNuxtConfig({
  i18n: {
    experimental: {
      hmr: true,
    },
  },
})

// After (v3.0.0)
export default defineNuxtConfig({
  i18n: {
    hmr: true,
  },
})

Breaking Changes

• fallbackRedirectComponentPath — Removed. The module no longer uses a fallback route component for redirects. If you had a custom component path configured, remove it from your config.
• useLocaleCookies — Removed. Use useI18nLocale() instead. The new composable provides locale, localeCookie, hashCookie, setLocale(), syncLocale(), and more.
• experimental.i18nPreviousPageFallback / previousPageFallback — Removed entirely. The cumulative merge strategy handles transition flickering automatically. Remove this option from your config.
• experimental.hmr — Moved to hmr. Update your config if you were using this option.
• Custom plugins — If your custom locale-detection plugin used useRuntimeConfig().public.i18nConfig, switch to getI18nConfig() from #build/i18n.strategy.mjs. Prefer useI18nLocale().setLocale() over useState('i18n-locale'). See Custom Language Detection for updated examples.
• Internal file changes — load-from-storage.ts and translation-loader.ts have been removed and replaced with storage.ts and server-loader.ts. If you were importing from these files directly (not recommended), update your imports.

Why It Matters

• Performance: Centralized singleton cache eliminates per-request object creation and reduces GC pressure.
• Maintainability: Route and path logic live in dedicated packages with clear boundaries and types.
• Testing: Strategy behavior and edge cases are tested in isolation.
• Reliability: Split server (Nitro) and client redirect logic avoids timing issues when cookie/useState are set by user plugins.
• Serverless-ready: Nitro plugin runs in the same context as Nitro handlers, compatible with Edge/Workers.
• Documentation: Routing behavior is documented in the Strategy guide and in the path-strategy and route-strategy packages.

For upgrade notes and a full list of changes, see the changelog.