nuxt-i18n-micro 3.26.0 → 3.28.0

package/dist/runtime/utils/nuxt-i18n.d.ts

@@ -10,10 +10,19 @@ export interface RouteTranslationContext {
 }
 export type GetRouteTranslationContext = (route?: unknown) => RouteTranslationContext;
 export type LoadTranslationsChunk = (locale: string, routeName?: string) => Promise<Record<string, unknown>>;
+/** Why the active translation context changed — used by Vue DevTools timeline. */
+export type I18nContextChangeReason = 'load' | 'refresh';
 export interface NuxtI18nOptions extends BaseI18nOptions {
+    /**
+     * Cap for `storage.translations` chunk entries (`locale:route`).
+     * `0` means no limit. Same module option as the fetch/server `CacheControl` layers.
+     * @default 0
+     */
+    cacheMaxSize?: number;
 }
 export declare class NuxtI18n extends BaseI18n {
     readonly storage: TranslationStorage;
+    private readonly cacheMaxSize;
     private readonly contextSignal;
     private cachedTranslations;
     /**
@@ -26,6 +35,8 @@ export declare class NuxtI18n extends BaseI18n {
     private currentLocale;
     private currentRouteName;
     private resolveRouteContext?;
+    private readonly contextListeners;
+    private missingKeyListener?;
     constructor(options?: NuxtI18nOptions);
     setRouteContextResolver(resolver: GetRouteTranslationContext): void;
     getCacheKey(locale: string, routeName?: string): string;
@@ -43,11 +54,22 @@ export declare class NuxtI18n extends BaseI18n {
     seedChunks(chunks: Record<string, Record<string, unknown>>): void;
     hasChunk(locale: string, routeName?: string): boolean;
     mergeChunk(locale: string, routeName: string | undefined, data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * FIFO eviction for `storage.translations` when `cacheMaxSize` is set.
+     * Prefers keeping the just-written key and the active page chunk. When those
+     * two differ and `max` cannot hold both (e.g. `cacheMaxSize: 1`), the just-written
+     * key wins so the configured bound is always enforced. Active `$t` still resolves
+     * via `cachedTranslations` / `outgoingTranslations` even if the Map drops the old key.
+     */
+    private evictChunks;
     getLocale(): string;
     getFallbackLocale(): string;
     getRoute(): string;
     getCurrentLocale(): string;
     getCurrentRouteName(): string;
+    onContextChange(listener: (reason: I18nContextChangeReason) => void): () => void;
+    onMissingKey(listener: (locale: string, key: string, routeName: string) => void): () => void;
+    private notifyContextChange;
     /**
      * Hot-reload the active dictionary for the next route — replace, don't merge.
      *
@@ -82,11 +104,11 @@ export declare class NuxtI18n extends BaseI18n {
      * first makes the change vanish on the next navigation.
      */
     setTranslation(key: TranslationKey, value: unknown): void;
-    protected getMissingContext(_routeContext?: unknown): {
+    protected getMissingContext(routeContext?: unknown): {
         locale: string;
         routeName: string;
     };
-    protected warnMissing(key: TranslationKey): void;
+    protected warnMissing(key: TranslationKey, routeContext?: unknown): void;
     clearCache(): void;
 }
 export interface NuxtTranslationLoaderOptions {

package/dist/runtime/utils/nuxt-i18n.js

@@ -32,6 +32,7 @@ function extractSwitchLocalePath(localeRoute, resolveRouter) {
 }
 export class NuxtI18n extends BaseI18n {
   storage;
+  cacheMaxSize;
   contextSignal;
   cachedTranslations = {};
   /**
@@ -44,12 +45,16 @@ export class NuxtI18n extends BaseI18n {
   currentLocale = "";
   currentRouteName = "";
   resolveRouteContext;
+  contextListeners = /* @__PURE__ */ new Set();
+  missingKeyListener;
   constructor(options = {}) {
+    const { cacheMaxSize = 0, ...baseOptions } = options;
     const storage = {
       translations: /* @__PURE__ */ new Map()
     };
-    super({ ...options, storage });
+    super({ ...baseOptions, storage });
     this.storage = storage;
+    this.cacheMaxSize = cacheMaxSize;
     this.contextSignal = shallowRef(0);
   }
   setRouteContextResolver(resolver) {
@@ -62,7 +67,9 @@ export class NuxtI18n extends BaseI18n {
     return this.storage.translations.get(this.getCacheKey(locale, routeName)) ?? {};
   }
   setChunk(locale, routeName, data) {
-    this.storage.translations.set(this.getCacheKey(locale, routeName), data);
+    const key = this.getCacheKey(locale, routeName);
+    this.storage.translations.set(key, data);
+    this.evictChunks(key);
   }
   /**
    * Install SSR chunks from the payload into the view layer.
@@ -74,11 +81,14 @@ export class NuxtI18n extends BaseI18n {
    * Existing entries win: anything already loaded is kept as-is.
    */
   seedChunks(chunks) {
+    let lastKey = "";
     for (const [cacheKey, data] of Object.entries(chunks)) {
       if (!this.storage.translations.has(cacheKey)) {
         this.storage.translations.set(cacheKey, data);
+        lastKey = cacheKey;
       }
     }
+    if (lastKey) this.evictChunks(lastKey);
   }
   hasChunk(locale, routeName) {
     return this.storage.translations.has(this.getCacheKey(locale, routeName));
@@ -88,8 +98,32 @@ export class NuxtI18n extends BaseI18n {
     const existing = this.storage.translations.get(cacheKey) ?? {};
     const merged = mergeTranslationChunk(existing, data);
     this.storage.translations.set(cacheKey, merged);
+    this.evictChunks(cacheKey);
     return merged;
   }
+  /**
+   * FIFO eviction for `storage.translations` when `cacheMaxSize` is set.
+   * Prefers keeping the just-written key and the active page chunk. When those
+   * two differ and `max` cannot hold both (e.g. `cacheMaxSize: 1`), the just-written
+   * key wins so the configured bound is always enforced. Active `$t` still resolves
+   * via `cachedTranslations` / `outgoingTranslations` even if the Map drops the old key.
+   */
+  evictChunks(keep) {
+    const max = this.cacheMaxSize;
+    if (max <= 0 || this.storage.translations.size <= max) return;
+    const current = this.getCacheKey(this.currentLocale, this.currentRouteName);
+    for (const key of this.storage.translations.keys()) {
+      if (this.storage.translations.size <= max) break;
+      if (key === keep || key === current) continue;
+      this.storage.translations.delete(key);
+    }
+    if (this.storage.translations.size <= max) return;
+    for (const key of this.storage.translations.keys()) {
+      if (this.storage.translations.size <= max) break;
+      if (key === keep) continue;
+      this.storage.translations.delete(key);
+    }
+  }
   getLocale() {
     return this.currentLocale;
   }
@@ -105,6 +139,25 @@ export class NuxtI18n extends BaseI18n {
   getCurrentRouteName() {
     return this.currentRouteName;
   }
+  onContextChange(listener) {
+    this.contextListeners.add(listener);
+    return () => {
+      this.contextListeners.delete(listener);
+    };
+  }
+  onMissingKey(listener) {
+    this.missingKeyListener = listener;
+    return () => {
+      if (this.missingKeyListener === listener) {
+        this.missingKeyListener = void 0;
+      }
+    };
+  }
+  notifyContextChange(reason) {
+    for (const listener of this.contextListeners) {
+      listener(reason);
+    }
+  }
   /**
    * Hot-reload the active dictionary for the next route — replace, don't merge.
    *
@@ -116,29 +169,33 @@ export class NuxtI18n extends BaseI18n {
    * and correct for the short hot-reload window.
    */
   applySwitchContext(locale, routeName, data) {
-    this.setChunk(locale, routeName, data);
     this.outgoingTranslations = this.currentLocale === locale ? this.cachedTranslations : null;
     this.cachedTranslations = data;
     this.currentLocale = locale;
     this.currentRouteName = routeName || "";
+    this.setChunk(locale, routeName, data);
     triggerRef(this.contextSignal);
+    this.notifyContextChange("load");
   }
   /** The outgoing page has unmounted, so its keys must stop resolving. */
   finishTransition() {
     if (this.outgoingTranslations === null) return;
     this.outgoingTranslations = null;
     triggerRef(this.contextSignal);
+    this.notifyContextChange("refresh");
   }
   mergeTranslations(newTranslations) {
     this.mergeChunk(this.currentLocale, this.currentRouteName, newTranslations);
     this.cachedTranslations = deepMergeTranslationsRecursive(this.cachedTranslations, newTranslations);
     triggerRef(this.contextSignal);
+    this.notifyContextChange("load");
   }
   async loadPageTranslations(locale, routeName, translations) {
     this.mergeChunk(locale, routeName, translations);
     if (locale === this.currentLocale && routeName === this.currentRouteName) {
       this.cachedTranslations = deepMergeTranslationsRecursive(this.cachedTranslations, translations);
       triggerRef(this.contextSignal);
+      this.notifyContextChange("load");
     }
   }
   async mergeTranslationAsync(locale, routeName, newTranslations, loadIfMissing) {
@@ -150,6 +207,7 @@ export class NuxtI18n extends BaseI18n {
     if (locale === this.currentLocale && routeName === this.currentRouteName) {
       this.cachedTranslations = deepMergeTranslationsRecursive(this.cachedTranslations, newTranslations);
       triggerRef(this.contextSignal);
+      this.notifyContextChange("load");
     }
   }
   tForRoute(route) {
@@ -201,18 +259,24 @@ export class NuxtI18n extends BaseI18n {
       setTranslationAtKey(this.getChunk(this.currentLocale, this.currentRouteName), String(key), value)
     );
     triggerRef(this.contextSignal);
+    this.notifyContextChange("refresh");
   }
-  getMissingContext(_routeContext) {
+  getMissingContext(routeContext) {
+    if (routeContext && this.resolveRouteContext) {
+      return this.resolveRouteContext(routeContext);
+    }
     return { locale: this.currentLocale, routeName: this.currentRouteName };
   }
-  warnMissing(key) {
+  warnMissing(key, routeContext) {
+    const { locale, routeName } = this.getMissingContext(routeContext);
+    this.missingKeyListener?.(locale, String(key), routeName);
     const customHandler = this.getCustomMissingHandler?.();
     if (customHandler) {
-      customHandler(this.currentLocale, String(key), this.currentRouteName);
+      customHandler(locale, String(key), routeName);
       return;
     }
     if (this.missingWarn && process.env.NODE_ENV !== "production" && import.meta.client) {
-      console.warn(`[i18n] Missing key '${key}' in '${this.currentLocale}' for route '${this.currentRouteName}'`);
+      console.warn(`[i18n] Missing key '${key}' in '${locale}' for route '${routeName}'`);
     }
   }
   clearCache() {
@@ -220,6 +284,7 @@ export class NuxtI18n extends BaseI18n {
     this.cachedTranslations = {};
     this.outgoingTranslations = null;
     triggerRef(this.contextSignal);
+    this.notifyContextChange("refresh");
   }
 }
 export class NuxtTranslationLoader {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-i18n-micro",
-  "version": "3.26.0",
-  "description": "Nuxt I18n Micro is a lightweight, high-performance internationalization module for Nuxt, designed to handle multi-language support with minimal overhead, fast build times, and efficient runtime performance.",
+  "version": "3.28.0",
+  "description": "Fast, lightweight i18n for Nuxt with strategy-based routing and minimal overhead.",
   "keywords": [
     "i18n",
     "internationalization",
@@ -14,7 +14,7 @@
     "seo",
     "translation"
   ],
-  "homepage": "https://github.com/s00d/nuxt-i18n-micro",
+  "homepage": "https://s00d.github.io/nuxt-i18n-micro/",
   "bugs": {
     "url": "https://github.com/s00d/nuxt-i18n-micro/issues"
   },
@@ -27,6 +27,7 @@
   "repository": "s00d/nuxt-i18n-micro",
   "workspaces": [
     "client",
+    "docs",
     "packages/**",
     "test/fixtures/**/*"
   ],
@@ -81,38 +82,38 @@
     "sirv": "^2.0.3",
     "ufo": "^1.5.4",
     "unplugin": "^1.16.1 || ^2.0.0 || ^3.3.0",
-    "@i18n-micro/path-strategy": "^1.3.9",
-    "@i18n-micro/test-utils": "^1.2.8",
-    "@i18n-micro/core": "^1.3.11",
-    "@i18n-micro/hmr": "^1.0.6",
-    "@i18n-micro/types": "^1.2.10",
-    "@i18n-micro/utils": "^1.0.13",
-    "@i18n-micro/route-strategy": "^1.1.14"
+    "@i18n-micro/route-strategy": "^1.1.15",
+    "@i18n-micro/core": "^1.3.13",
+    "@i18n-micro/hmr": "^1.0.7",
+    "@i18n-micro/types": "^1.2.11",
+    "@i18n-micro/path-strategy": "^1.3.10",
+    "@i18n-micro/utils": "^1.0.14",
+    "@i18n-micro/test-utils": "^1.2.9"
   },
   "devDependencies": {
     "@nuxt/devtools": "^3.3.1",
     "@nuxt/devtools-ui-kit": "^3.3.1",
+    "@vue/devtools-api": "^8.1.5",
     "@nuxt/module-builder": "^1.0.0",
     "@nuxt/schema": "^3.18.1 || ^4.0.0",
     "@nuxt/test-utils": "^4.0.3",
     "@playwright/test": "^1.55.0",
     "@types/node": "^20.19.26",
     "changelogen": "^0.5.7",
-    "chart.js": "^4.5.1",
-    "mermaid": "^11.12.2",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.58.0",
     "typescript": "^5.9.3",
-    "vitepress": "^2.0.0-alpha.18",
-    "vitepress-plugin-chartjs": "^1.2.1",
-    "vitepress-plugin-folder-tree": "^1.2.1",
-    "vitepress-plugin-llms": "^1.13.3",
-    "vitepress-plugin-mermaid": "^2.0.17",
     "vitest": "^4.1.10",
     "vue-tsc": "^2.0.21"
   },
   "peerDependencies": {
-    "vue-router": "^4.6.3 || ^5.0.0"
+    "vue-router": "^4.6.3 || ^5.0.0",
+    "@vue/devtools-api": "^8.1.5"
+  },
+  "peerDependenciesMeta": {
+    "@vue/devtools-api": {
+      "optional": true
+    }
   },
   "optionalDependencies": {
     "@rollup/rollup-linux-x64-gnu": "^4.28.1",
@@ -161,11 +162,11 @@
     "test:dist:packages": "pnpm --filter \"@i18n-micro/core\" --filter \"@i18n-micro/utils\" --filter \"@i18n-micro/hmr\" --filter \"@i18n-micro/vue\" --filter \"@i18n-micro/path-strategy\" --filter \"@i18n-micro/route-strategy\" --filter \"@i18n-micro/devtools-ui\" --filter \"@i18n-micro/astro\" run test:dist",
     "typecheck": "tsc --noEmit",
     "typecheck:nuxt": "nuxt typecheck --no-emit",
-    "docs:dev": "pnpm run docs:generate && vitepress dev docs",
-    "docs:build": "pnpm run docs:generate && vitepress build docs",
-    "docs:serve": "vitepress serve docs",
-    "docs:clean-dev": "pnpm run docs:generate && vitepress dev docs --clean-cache",
-    "docs:preview": "vitepress preview docs",
+    "docs:dev": "pnpm --filter @i18n-micro/docs dev",
+    "docs:build": "pnpm --filter @i18n-micro/docs build",
+    "docs:serve": "pnpm --filter @i18n-micro/docs preview",
+    "docs:clean-dev": "pnpm --filter @i18n-micro/docs clean-dev",
+    "docs:preview": "pnpm --filter @i18n-micro/docs preview",
     "smoke:pack": "pnpm -C scripts cli smoke-pack",
     "smoke:verify": "pnpm -C scripts cli smoke-verify",
     "smoke:browser": "pnpm -C scripts cli smoke-browser",

package/dist/client/_nuxt/builds/meta/24f3c578-f02b-41bc-953a-c7ff7b504d56.json

@@ -1 +0,0 @@
-{"id":"24f3c578-f02b-41bc-953a-c7ff7b504d56","timestamp":1785527483273,"prerendered":[]}

package/dist/client/_nuxt/error-404.Cr1POox6.css

@@ -1 +0,0 @@
-.grid[data-v-2a91edc4]{display:grid}.mb-2[data-v-2a91edc4]{margin-bottom:.5rem}.mb-4[data-v-2a91edc4]{margin-bottom:1rem}.max-w-520px[data-v-2a91edc4]{max-width:520px}.min-h-screen[data-v-2a91edc4]{min-height:100vh}.w-full[data-v-2a91edc4]{width:100%}.flex[data-v-2a91edc4]{display:flex}.place-content-center[data-v-2a91edc4]{place-content:center}.items-center[data-v-2a91edc4]{align-items:center}.justify-center[data-v-2a91edc4]{justify-content:center}.overflow-hidden[data-v-2a91edc4]{overflow:hidden}.bg-white[data-v-2a91edc4]{--un-bg-opacity:1;background-color:rgb(255 255 255/var(--un-bg-opacity))}.px-2[data-v-2a91edc4]{padding-left:.5rem;padding-right:.5rem}.text-center[data-v-2a91edc4]{text-align:center}.text-\[80px\][data-v-2a91edc4]{font-size:80px}.text-2xl[data-v-2a91edc4]{font-size:1.5rem;line-height:2rem}.text-sm[data-v-2a91edc4]{font-size:.875rem;line-height:1.25rem}.text-\[\#020420\][data-v-2a91edc4]{--un-text-opacity:1;color:rgb(2 4 32/var(--un-text-opacity))}.text-\[\#64748B\][data-v-2a91edc4]{--un-text-opacity:1;color:rgb(100 116 139/var(--un-text-opacity))}.hover\:text-\[\#00DC82\][data-v-2a91edc4]:hover{--un-text-opacity:1;color:rgb(0 220 130/var(--un-text-opacity))}.font-medium[data-v-2a91edc4]{font-weight:500}.font-semibold[data-v-2a91edc4]{font-weight:600}.leading-none[data-v-2a91edc4]{line-height:1}.tracking-wide[data-v-2a91edc4]{letter-spacing:.025em}.font-sans[data-v-2a91edc4]{font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,Noto Sans,sans-serif,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji}.tabular-nums[data-v-2a91edc4]{--un-numeric-spacing:tabular-nums;font-variant-numeric:var(--un-ordinal) var(--un-slashed-zero) var(--un-numeric-figure) var(--un-numeric-spacing) var(--un-numeric-fraction)}.underline[data-v-2a91edc4]{text-decoration-line:underline}.underline-offset-3[data-v-2a91edc4]{text-underline-offset:3px}.antialiased[data-v-2a91edc4]{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}@media (prefers-color-scheme:dark){.dark\:bg-\[\#020420\][data-v-2a91edc4]{--un-bg-opacity:1;background-color:rgb(2 4 32/var(--un-bg-opacity))}.dark\:text-white[data-v-2a91edc4]{--un-text-opacity:1;color:rgb(255 255 255/var(--un-text-opacity))}}@media (width>=640px){.sm\:text-\[110px\][data-v-2a91edc4]{font-size:110px}.sm\:text-3xl[data-v-2a91edc4]{font-size:1.875rem;line-height:2.25rem}}

package/dist/client/_nuxt/error-500.BcWSpGYy.css

@@ -1 +0,0 @@
-.grid[data-v-f975ae25]{display:grid}.mb-2[data-v-f975ae25]{margin-bottom:.5rem}.mb-4[data-v-f975ae25]{margin-bottom:1rem}.max-w-520px[data-v-f975ae25]{max-width:520px}.min-h-screen[data-v-f975ae25]{min-height:100vh}.place-content-center[data-v-f975ae25]{place-content:center}.overflow-hidden[data-v-f975ae25]{overflow:hidden}.bg-white[data-v-f975ae25]{--un-bg-opacity:1;background-color:rgb(255 255 255/var(--un-bg-opacity))}.px-2[data-v-f975ae25]{padding-left:.5rem;padding-right:.5rem}.text-center[data-v-f975ae25]{text-align:center}.text-\[80px\][data-v-f975ae25]{font-size:80px}.text-2xl[data-v-f975ae25]{font-size:1.5rem;line-height:2rem}.text-\[\#020420\][data-v-f975ae25]{--un-text-opacity:1;color:rgb(2 4 32/var(--un-text-opacity))}.text-\[\#64748B\][data-v-f975ae25]{--un-text-opacity:1;color:rgb(100 116 139/var(--un-text-opacity))}.font-semibold[data-v-f975ae25]{font-weight:600}.leading-none[data-v-f975ae25]{line-height:1}.tracking-wide[data-v-f975ae25]{letter-spacing:.025em}.font-sans[data-v-f975ae25]{font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,Noto Sans,sans-serif,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji}.tabular-nums[data-v-f975ae25]{--un-numeric-spacing:tabular-nums;font-variant-numeric:var(--un-ordinal) var(--un-slashed-zero) var(--un-numeric-figure) var(--un-numeric-spacing) var(--un-numeric-fraction)}.antialiased[data-v-f975ae25]{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}@media (prefers-color-scheme:dark){.dark\:bg-\[\#020420\][data-v-f975ae25]{--un-bg-opacity:1;background-color:rgb(2 4 32/var(--un-bg-opacity))}.dark\:text-white[data-v-f975ae25]{--un-text-opacity:1;color:rgb(255 255 255/var(--un-text-opacity))}}@media (width>=640px){.sm\:text-\[110px\][data-v-f975ae25]{font-size:110px}.sm\:text-3xl[data-v-f975ae25]{font-size:1.875rem;line-height:2.25rem}}