@intlify/unplugin-vue-i18n

@intlify/unplugin-vue-i18n is the official build-tool integration for Vue I18n, built on the unplugin abstraction so the same plugin logic runs identically under Vite, Webpack, and Rspack. Its core job is precompilation: instead of shipping raw JSON/YAML locale resources that Vue I18n has to parse and compile to message functions at runtime, this plugin runs vue-i18n’s message compiler at build time and emits ready-to-run JavaScript, cutting both parse cost and bundle size.

Beyond precompilation, it understands Vue single-file components directly — parsing <i18n> custom blocks out of .vue files (in JSON, JSON5, YAML, or YML) and turning them into locale message imports the same way vue-i18n-loader and vite-plugin-vue-i18n did in earlier, now-unmaintained incarnations of the same idea. It can also bundle all resources under a project’s include glob into a single virtual module (@intlify/unplugin-vue-i18n/messages) for one-shot dynamic imports, and it automatically selects the correct Vue I18n build (full vs. runtime-only, ESM-bundler vs. CJS) for development versus production so consumers don’t have to hand-tune bundler aliases themselves.

What You Get

• Locale message precompilation to JavaScript or AST at build time, avoiding vue-i18n’s runtime message compiler in production
• Native parsing of <i18n> custom blocks inside .vue SFCs, in JSON, JSON5, YAML, or YML format
• A virtual @intlify/unplugin-vue-i18n/messages module that merges every matched locale file into one importable object, with generated TypeScript types
• Automatic vue-i18n build selection (composition-only, runtime-only, full vs. tree-shaken legacy API) so production bundles stay small without manual bundler aliasing
• One plugin implementation shared across Vite, Webpack, and Rspack via the unplugin abstraction, plus first-class Nuxt usage
• Fine-grained content controls — HTML-tag strict-mode checking, HTML escaping, locale filtering via onlyLocales, and a transformI18nBlock hook for custom preprocessing

Common Use Cases

• A Vue 3 app with dozens of locale JSON/YAML files that wants them precompiled once at build time instead of parsed by every client at runtime
• A component library that ships translations colocated with each .vue file as inline <i18n> custom blocks rather than a separate resource tree
• A Nuxt project that needs the same i18n build behavior whether it’s building with Vite or Webpack
• A team migrating off the older, now-archived vue-i18n-loader / vite-plugin-vue-i18n / rollup-plugin-vue-i18n packages onto their unplugin-based, actively maintained successor
• A performance-sensitive app that wants to drop the legacy Options API translation surface and JIT message compiler entirely via compositionOnly and dropMessageCompiler

Under The Hood

Architecture The plugin is a thin unplugin factory (src/index.ts) that validates the host bundler (vite/webpack/rspack only) and delegates to a single resourcePlugin defined in src/core/resource.ts, a ~780-line module that is the actual engine: it builds bundler-specific include/exclude filters via @rollup/pluginutils’s createFilter, distinguishes plain resource files (json/json5/yaml/yml/js/ts) from SFC <i18n> custom blocks using regexes tuned separately for Vite’s query-string convention and Webpack/Rspack’s blockType convention, and generates code through @intlify/bundle-utils’s generateJSON/generateYAML/generateJavaScript/generateTypescript helpers. A parallel src/vue/ module (query.ts, utils.ts) isolates the SFC-descriptor and Vue-compiler-version handling needed to parse <i18n> blocks consistently. Options resolution is centralized in src/core/options.ts, keeping the option-normalization logic (e.g. the include/exclude legacy-default quirk called out in code comments) in one place rather than duplicated per bundler branch.

Tech Stack TypeScript throughout, built with unbuild and distributed as dual ESM/CJS output per entry point (vite, webpack, rspack, root). It depends on the sibling workspace package @intlify/bundle-utils for the actual message-compiler code generation, plus @rollup/pluginutils for filtering, mlly for static-import analysis, knitwork for safe import-statement generation, tinyglobby for fast globbing, and vue/compiler-sfc for parsing .vue files. It’s a pnpm-workspace monorepo (intlify/bundle-tools) that also hosts the bundle-utils package and a set of Vite/Webpack/Rspack example apps used for manual verification.

Code Quality Testing is extensive and bundler-parametrized: the same Vitest suite (custom-block.test.ts, resource-compilation.test.ts, bundle-import.test.ts, sourcemap.test.ts, hmr-glob.test.ts, query.test.ts) is re-run per target via TEST_FRAMEWORK=vite|webpack|rspack environment switches, plus separate Vite 6/7/8 compatibility passes, and a dedicated Playwright-backed e2e suite for HMR behavior. CI runs tsc --noEmit for typechecking ahead of unit tests. Linting combines eslint with a large curated plugin set (unicorn, regexp, promise, import, jsonc, yml, markdown-preferences) plus knip for unused-export/dependency detection, and Prettier for formatting — both gated in CI per the repo’s lint/test badges.

What Makes It Unique Rather than being written as three separate bundler-specific plugins the way its predecessors (vue-i18n-loader, vite-plugin-vue-i18n, rollup-plugin-vue-i18n, all retained read-only under .unmaintained/ in this repo) were, it consolidates one implementation on top of the unplugin abstraction so Vite, Webpack, and Rspack users get identical behavior and options from a single maintained codebase. Its automatic build-target selection (choosing runtime-only vs. full, JIT vs. AOT compiled vue-i18n builds per environment) removes a class of manual bundler-alias configuration that most i18n integrations leave entirely to the consumer.