v3.19.0

Date: 2026-05-25

Version: v3.19.0

This release focuses on modularizing internal utilities, adding a compact serverless payload mode, and reusing shared logic across Nuxt, Node, Astro, and DevTools — without changing the public module API for typical apps.

What's New?

@i18n-micro/utils — Framework-Agnostic Utilities

Shared logic previously scattered across src/runtime/utils/ and src/module.ts now lives in a dedicated workspace package with granular subpath imports (no fat barrel, tree-shake friendly):

• Build — preMergeLocales, buildTranslationSourceLayers (@i18n-micro/utils/build)
• Payloads — translationPayloads resolution, URL building, fetch helpers, stats (payload-config, payload-url, payload-fetch, payload-stats)
• Source mode — fallback chains, source file paths, runtime merge (merge-source, source-loader)
• Runtime helpers — locale resolution, cookies, Accept-Language parsing, route/meta helpers (resolve-locale, accept-language, cookie, route, route-pattern, runtime-config)
• Shared FS paths — translation file classification, nested page paths (parse-path)

The Nuxt module keeps thin glue in src/runtime/ and imports only the subpaths it needs.

@i18n-micro/hmr — Dev Translation Hot Reload

Development HMR is extracted into @i18n-micro/hmr:

• watcher — file change handling, cache invalidation, source/premerged merge in dev
• generate-plugin — client-side HMR plugin generation
• cache-keys — shared Symbol.for keys for server/storage caches

Works with both translationPayloads.mode: 'premerged' and 'source'.

translationPayloads.mode: 'source' — Compact Serverless Deployments

New payload mode for large locale matrices on serverless platforms (Cloudflare Workers, etc.):

export default defineNuxtConfig({
  i18n: {
    translationPayloads: {
      mode: 'source',
    },
  },
})

• Bundles compact source files into Nitro assets instead of a full pre-merged matrix
• Merges root, page, and fallback locale chains at runtime via the built-in /_locales/:page/:locale/data.json route
• Defaults publicAssets and prerenderRoutes to false — ideal when you rely on a Nitro/edge runtime rather than pure static hosting

See Deployment — serverless and Edge and Cache & Storage Architecture.

Shared Utilities Across Integration Packages

• @i18n-micro/node and @i18n-micro/astro — unified translation path parsing and deep merge via @i18n-micro/utils/parse-path
• @i18n-micro/astro — detectLocaleFromAcceptLanguage from @i18n-micro/utils/accept-language (removed duplicate parser)
• @i18n-micro/devtools-ui — virtual file paths via merge-source + parse-path helpers
• Server locale detection — Accept-Language handling aligned with shared utils

HMR & DevTools Fixes

• Client HMR plugin now calls $loadPageTranslations (correct API) instead of the removed $loadTranslations
• Playwright coverage for translation watcher in premerged and source modes

Documentation & Contributor Guide

• Cache & Storage Architecture — documents both payload modes and package boundaries
• Server-Side Translations, Getting Started, Folder Structure — premerged vs source caveats
• Contribution Guide — Node 18+, pnpm 9+, Oxlint/Oxfmt, monorepo layout with packages/utils and packages/hmr

Breaking Changes (Advanced / Internal)

These affect only projects that imported internal module paths (not part of the public API):

• Removed from src/runtime/utils/: route-utils.ts, runtime-i18n-config.ts, and other utilities moved to @i18n-micro/utils/*
• Removed from src/runtime/server/plugins/: inline HMR watcher/generator — use @i18n-micro/hmr/* if you forked dev tooling
• nuxt-i18n-micro now depends on @i18n-micro/utils and @i18n-micro/hmr workspace packages (installed automatically with the module)

Typical nuxt.config + composables usage is unchanged.

Why It Matters

• Smaller serverless bundles — source mode avoids shipping a pre-merged file per locale × page
• Single source of truth — one implementation for path parsing, merge, locale detection, and payload config
• Easier maintenance — framework-agnostic code is tested in @i18n-micro/utils (50+ unit tests) and reused everywhere
• Better dev UX — HMR logic is isolated, testable, and consistent across payload modes

For the full commit list, see the changelog.