@intlayer/docs 9.4.2 → 9.4.4

package/blog/en/is_vue-i18n_outdated.md

@@ -0,0 +1,338 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: Is vue-i18n Outdated in 2026?
+description: vue-i18n has been the standard for Vue and Nuxt apps for a decade. But in our benchmarks, it proved to be the heaviest i18n runtime on the web. Here is why.
+keywords:
+  - vue-i18n
+  - Intlayer
+  - Internationalization
+  - i18n
+  - Vue
+  - Nuxt
+  - Bundle size
+  - Blog
+slugs:
+  - blog
+  - is-vue-i18n-outdated
+author: aymericzip
+---
+
+# Is vue-i18n Outdated in 2026?
+
+In the Vue community, few libraries are as widely adopted as `vue-i18n`. Maintained by Kazupon since Vue 2, it powers `@nuxtjs/i18n` and serves as the default choice for virtually every multilingual Vue app.
+
+Yet in our 2026 benchmarks, we ran into an unexpected finding: **`vue-i18n` was the single heaviest localization runtime across all frontend frameworks tested.**
+
+On a clean 31.5 KB Vite + Vue baseline, adding `vue-i18n` pushed average page JavaScript to **136.4 KB**, more than quadrupling the payload.
+
+How did a framework known for being lightweight and nimble end up with such a heavy internationalization stack? And does its classic runtime model still make sense today?
+
+<TOC/>
+
+## Key Takeaways
+
+**Heaviest runtime benchmarked:**
+
+At **24.3 KB gzipped (83.2 KB minified)** before adding any content, `vue-i18n` is roughly **9x heavier** than `intlayer`'s 2.7 KB runtime.
+
+**A 330% payload penalty:**
+
+`vue-i18n` swelled a 31.5 KB baseline Vue page to 136.4 KB. Intlayer produced 59.3 KB, a **56% smaller page payload**.
+
+**The hidden runtime compiler:**
+
+By default, unless you configure specific bundler aliases, `vue-i18n` ships an entire message compiler to the browser to parse strings on the fly.
+
+**Maintenance velocity:**
+
+Over the past year, `vue-i18n` recorded ~259 commits, focused on patch fixes and Vue core compatibility.
+
+**No first-party modern tooling:**
+
+Missing first-party Language Server (LSP) support, AI MCP servers, or automated CLI translation pipelines.
+
+## Maintenance vs. Modern Tooling
+
+| Repository            | Stars                                                                                                                                                  | Total commits                                                                                                                                                       | Commits / year                                                                                                                                                     | Last commit                                                                                                                                  |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlify/vue-i18n`    | [![stars](https://img.shields.io/github/stars/intlify/vue-i18n?style=for-the-badge&label=stars)](https://github.com/intlify/vue-i18n/stargazers)       | [![commits](https://img.shields.io/github/commit-activity/t/intlify/vue-i18n?style=for-the-badge&label=commits)](https://github.com/intlify/vue-i18n/commits)       | [![yearly](https://img.shields.io/github/commit-activity/y/intlify/vue-i18n?style=for-the-badge&label=%2Fyear)](https://github.com/intlify/vue-i18n/commits)       | [![last](https://img.shields.io/github/last-commit/intlify/vue-i18n?style=for-the-badge)](https://github.com/intlify/vue-i18n/commits)       |
+| `aymericzip/intlayer` | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits) | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits) |
+
+Trailing twelve months:
+
+- `intlify/vue-i18n`: **259 commits** (routine patches and Vue 3 / Nuxt dependency maintenance).
+- `aymericzip/intlayer`: **4,343 commits** (active work across compiler optimizations, LSP tools, and AI agents).
+
+[![Star History Chart](https://api.star-history.com/chart?repos=intlify%2Fvue-i18n%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
+
+A mature library can be complete. But modern frontends now leverage build-time AST transformations, bundler dead-code elimination, and AI-driven localization. A runtime-bound architecture cannot easily adopt these paradigms.
+
+## Measuring Performance in Vite + Vue
+
+We benchmarked a 10-page, 10-locale application built with Vite and Vue 3:
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vite_vue.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Tested in a real browser using production gzip compression. Full data in the [Vue benchmark documentation](https://intlayer.org/doc/benchmark/vue).
+
+### Baseline Framework Overhead
+
+Overhead before adding any translation strings:
+
+| Library           | Gzipped    | Minified   |
+| ----------------- | ---------- | ---------- |
+| `vue-i18n@11.4.0` | 24.3 KB    | 83.2 KB    |
+| `intlayer@8.7.12` | **2.7 KB** | **7.6 KB** |
+
+`vue-i18n`’s runtime alone weighs **24.3 KB gzipped**, nearly the weight of Vue core itself. Intlayer adds just **2.7 KB**.
+
+### Page Weight and Leakage
+
+| Setup          | Page JS avg (gz) | Locale leak | Other-page leak | Avg component (gz) |
+| -------------- | ---------------- | ----------- | --------------- | ------------------ |
+| Base (no i18n) | 31.5 KB          | 0.0%        | 90.0%           | 0.9 KB             |
+| `vue-i18n`     | **136.4 KB**     | 50.2%       | 90.0%           | 196.0 KB           |
+| Intlayer       | **59.3 KB**      | 51.1%       | **0.0%**        | **6.5 KB**         |
+
+### Key Findings
+
+**Substantial relative bloat:**
+
+Because baseline Vue is so lean (~31 KB), `vue-i18n` more than quadruples the page payload.
+
+**Other-page leakage:**
+
+By default, **90% of localized text** sent to a route belongs to other pages. Intlayer strips this entirely to **0.0%**.
+
+**Isolated component weight:**
+
+Components compiled with localized scopes averaged 196 KB with `vue-i18n` because catalogs were duplicated inside them, versus **6.5 KB** with Intlayer.
+
+## Why Is vue-i18n Heavy?
+
+### An AST Compiler Shipped to the Browser
+
+`vue-i18n` contains its own message format compiler. Plural rules and interpolations are parsed into Abstract Syntax Trees at runtime.
+
+Avoiding this requires configuring bundler aliases for `vue-i18n/dist/vue-i18n.runtime.esm-bundler.js` and pre-compiling catalogs via `@intlify/unplugin-vue-i18n`. Many projects miss this step, inadvertently shipping an entire compiler to end users.
+
+### Monolithic Feature Set
+
+`vue-i18n` includes number and datetime engines, linked message resolvers, legacy Options API bridges (`$t`, `v-t`), and reactive message proxies. Even if you only need plain string translations in `<script setup>`, you pay for the entire suite.
+
+### Dynamic Keys Defeat Tree-Shaking
+
+Because `"home.hero.title"` is evaluated at runtime, bundlers cannot verify which keys are accessed. Unused strings in your message files cannot be tree-shaken.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="vue-i18n" value="vue-i18n">
+
+```vue fileName="Hero.vue"
+<script setup>
+import { useI18n } from "vue-i18n";
+
+const { t } = useI18n();
+</script>
+
+<template>
+  <h1>{{ t("home.hero.title") }}</h1>
+</template>
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```vue fileName="Hero.vue"
+<script setup>
+import { useIntlayer } from "vue-intlayer";
+
+const { title } = useIntlayer("hero");
+</script>
+
+<template>
+  <h1>{{ title }}</h1>
+</template>
+```
+
+  </Tab>
+</Tabs>
+
+The [Intlayer compiler](https://intlayer.org/doc/compiler) tracks exact properties and removes unreferenced content before building client chunks. See [bundle optimization](https://intlayer.org/doc/concept/bundle-optimization) for details.
+
+## Developer Experience
+
+### Disconnected Catalogs vs. Co-Location
+
+With `vue-i18n`, copy lives in a separate `locales/` directory. Intlayer co-locates typed content files directly beside components:
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="vue-i18n" value="vue-i18n">
+
+```json fileName="locales/en.json"
+{
+  "hero": {
+    "title": "Ship in every language"
+  }
+}
+```
+
+```json fileName="locales/fr.json"
+{
+  "hero": {
+    "title": "Livrez dans toutes les langues"
+  }
+}
+```
+
+```vue fileName="Hero.vue"
+<script setup>
+import { useI18n } from "vue-i18n";
+
+const { t } = useI18n();
+</script>
+
+<template>
+  <h1>{{ t("hero.title") }}</h1>
+</template>
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="Hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      fr: "Livrez dans toutes les langues",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```vue fileName="Hero.vue"
+<script setup>
+import { useIntlayer } from "vue-intlayer";
+
+const { title } = useIntlayer("hero");
+</script>
+
+<template>
+  <h1>{{ title }}</h1>
+</template>
+```
+
+  </Tab>
+</Tabs>
+
+When `Hero.vue` is deleted or refactored, its content file moves or gets removed with it.
+
+### Autocomplete vs. Strict Completeness
+
+`DefineLocaleMessage` provides IDE autocomplete against a canonical schema. However, it does not guarantee translation completeness. Omitting a key from `fr.json` raises no TypeScript error at build time.
+
+With Intlayer, dictionaries are validated strictly. Enabling [`strictMode`](https://intlayer.org/doc/concept/configuration) turns missing translations in any locale into hard compile errors.
+
+### Modern Tooling for AI & IDEs
+
+| Feature                   | `vue-i18n`              | Intlayer                                                               |
+| ------------------------- | ----------------------- | ---------------------------------------------------------------------- |
+| **VS Code Extension**     | Third-party (i18n Ally) | ✅ [First-party extension](https://intlayer.org/doc/vs-code-extension) |
+| **Language Server (LSP)** | ❌ None                 | ✅ [Integrated LSP](https://intlayer.org/doc/lsp)                      |
+| **MCP Server for AI**     | ❌ None                 | ✅ [Built-in MCP Server](https://intlayer.org/doc/mcp-server)          |
+| **Agent Skills**          | ❌ None                 | ✅ [Autonomous agent skills](https://intlayer.org/doc/agent_skills)    |
+| **Visual In-Context CMS** | ❌ None                 | ✅ [Free & Open Source CMS](https://intlayer.org/doc/concept/editor)   |
+
+## Translation Pipelines
+
+`vue-i18n` does not offer a native translation command. Teams typically export JSON to third-party platforms like Crowdin or Phrase.
+
+Intlayer provides built-in tools:
+
+**Local AI auto-fill (`intlayer fill`):**
+
+Automatically translates missing keys using your own OpenAI, Anthropic, Mistral, or Gemini API keys.
+
+**Self-hostable visual CMS:**
+
+Use the [Intlayer CMS](https://intlayer.org/doc/concept/cms) to let non-developers edit copy while changes commit directly to Git.
+
+**Permissive open-source license:**
+
+The entire toolkit is Apache 2.0.
+
+## When vue-i18n is Still the Right Choice
+
+<AccordionGroup>
+<Accordion header="Large legacy Nuxt 2/3 applications">
+
+If your routing architecture is deeply coupled to `@nuxtjs/i18n` and running stably, a rewrite may not provide an immediate return on investment.
+
+</Accordion>
+<Accordion header="Complex ICU formatting">
+
+If you rely extensively on linked messages, complex datetime formatters, or intricate custom plural rules.
+
+</Accordion>
+<Accordion header="Small hobby projects">
+
+If bundle size is not a constraint for your use case.
+
+</Accordion>
+</AccordionGroup>
+
+## How to Improve My Existing vue-i18n Setup?
+
+Intlayer offers drop-in compatibility packages that preserve the exact function signatures of `vue-i18n` and `@nuxtjs/i18n` (`useI18n`, `$t`, `<i18n-t>`). You do not need to rewrite your templates or composables to start benefiting from a lightweight, compiler-driven architecture.
+
+Setup takes a single command:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+This interactive CLI:
+
+1. Installs the `@intlayer/vue-i18n` or `@intlayer/nuxt-i18n` compatibility package.
+2. Configures Vite or Nuxt bundler aliases so your existing imports and template usages route seamlessly to Intlayer, allowing you to remove `vue-i18n` from `package.json`.
+3. Instantly enables language server (LSP) diagnostics, eliminates the 24 KB runtime AST parser from your client bundle, and unlocks local AI translation workflows without a major refactor.
+
+For step-by-step instructions, explore our dedicated guides:
+
+- **Drop-in Compatibility:** Keep existing templates using the [`vue-i18n` compatibility layer](https://intlayer.org/doc/compatibility/vue-i18n) or [`@nuxtjs/i18n` compatibility layer](https://intlayer.org/doc/compatibility/nuxtjs-i18n).
+- **Automated Migration Guides:** Convert legacy JSON files into structured dictionaries with our guides: [from vue-i18n](https://intlayer.org/doc/migration/vue-i18n) or [from @nuxtjs/i18n](https://intlayer.org/doc/migration/nuxtjs-i18n).
+- **Hybrid Setup:** Keep `vue-i18n` at runtime while [using Intlayer alongside vue-i18n](https://intlayer.org/blog/intlayer-with-vue-i18n) for local type safety and AI translation.
+
+Scan your live website for payload and leakage with the free [i18n SEO Scanner](https://intlayer.org/i18n-seo-scanner):
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Further Reading
+
+- [Vue & Vite i18n Benchmark: Complete Performance Analysis](https://intlayer.org/doc/benchmark/vue)
+- [vue-i18n vs Intlayer: Feature-by-Feature Comparison](https://intlayer.org/blog/vue-i18n-vs-intlayer)
+- [Is next-intl Outdated in 2026?](https://intlayer.org/blog/is-next-intl-outdated)
+- [Compiler vs. Declarative Internationalization](https://intlayer.org/blog/compiler-vs-declarative-i18n)

package/blog/en/list_i18n_technologies/build-tools/vite.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Vite i18n: glob imports, chunks and build-time messages"
+description: What is actually Vite-specific about i18n. Lazy catalogs with import.meta.glob, why per-route locale splitting rarely works, HMR gaps, and compile-time plugins.
+keywords:
+  - vite i18n
+  - import.meta.glob
+  - vite code splitting
+  - lazy load translations
+  - vite plugin i18n
+  - rollup chunks
+slugs:
+  - blog
+  - i18n-technologies
+  - build-tools
+  - vite
+author: aymericzip
+---
+
+# Vite i18n: the parts that are about Vite, not your framework
+
+Most "Vite i18n" tutorials are really React or Vue tutorials that happen to use Vite. This one is about the layer underneath: how catalogs get imported, what Rollup does with them, and why the lazy loading you wrote is probably not lazy.
+
+## Table of Contents
+
+<TOC/>
+
+## Static import is the default, and it is eager
+
+The simplest setup imports every catalog at the top of a module.
+
+```ts fileName="src/i18n.ts"
+import en from "./locales/en.json";
+import fr from "./locales/fr.json";
+import ja from "./locales/ja.json";
+```
+
+That is three catalogs in the entry chunk, on every page, for every user. It is fine for two locales and a hundred strings. At ten locales it is the single biggest avoidable cost in the bundle.
+
+## `import.meta.glob` and the flag everyone gets wrong
+
+Vite's glob import is the usual fix.
+
+```ts
+const catalogs = import.meta.glob("./locales/*.json");
+
+export const loadCatalog = async (locale: string) => {
+  const load = catalogs[`./locales/${locale}.json`];
+  return (await load()) as Record<string, string>;
+};
+```
+
+Lazy is the default: each entry is a function returning a dynamic import, and Rollup emits one chunk per file. Adding `{ eager: true }` inlines all of them into the importing module, which is exactly what you were trying to avoid.
+
+```ts
+// Every locale, in the entry chunk. Almost never what you want.
+const catalogs = import.meta.glob("./locales/*.json", { eager: true });
+```
+
+The trap is that both versions work in dev, because Vite serves modules unbundled. The difference only shows up in `dist`. Check with `npx vite build && npx vite preview`, then look at what the entry chunk actually contains.
+
+## Per-route splitting rarely splits
+
+This is the part that surprises people. You split catalogs by page:
+
+```
+locales/en/home.json
+locales/en/checkout.json
+```
+
+Then two routes both import `checkout.json`, and Rollup hoists it into a shared chunk that loads on both. Rollup's chunking is driven by the module graph, not by your folder names: a module reachable from more than one entry becomes common. Adding a third route that imports it changes nothing, and adding a fourth might split it differently.
+
+So per-route locale splitting only holds if the import graph really is disjoint. If it matters, verify it rather than assume it:
+
+```bash
+npx vite build && npx vite-bundle-visualizer
+```
+
+If you need to force the boundary, `build.rollupOptions.output.manualChunks` is the escape hatch, at the cost of maintaining it by hand.
+
+## Catalogs do not hot-reload
+
+Edit a component, Vite swaps it in. Edit `locales/fr.json`, and depending on how it was imported, nothing happens. JSON imported dynamically has no HMR boundary, so the module graph does not know to invalidate the consumers.
+
+People work around this by restarting the dev server every time they touch a string, usually without realising it is avoidable. The fix belongs to the i18n plugin: it has to accept the HMR update and push new messages into the running app. When you evaluate a library, check whether its Vite plugin does this, because it is a daily-friction thing rather than a production thing.
+
+## `define` bakes the locale in
+
+It is tempting to resolve the default locale at build time:
+
+```ts fileName="vite.config.ts"
+export default defineConfig({
+  define: {
+    __DEFAULT_LOCALE__: JSON.stringify(process.env.LOCALE ?? "en"),
+  },
+});
+```
+
+`define` is a textual replacement performed at build time. Whatever value is present when you build is the value that ships, so this forces one build per locale. That is a legitimate strategy, and it is exactly what Angular's official i18n does. It is not what you want if a single deployment has to serve every language.
+
+For values that must vary per request, keep them out of `define` and resolve them at runtime.
+
+## Moving message parsing to build time
+
+Every mature option in this ecosystem eventually does the same thing: stop parsing messages in the browser.
+
+| Plugin                       | What it moves to build time                                                          |
+| :--------------------------- | :----------------------------------------------------------------------------------- |
+| `@intlify/unplugin-vue-i18n` | Compiles vue-i18n messages to render functions, lets you ship the runtime-only build |
+| Lingui (macro plus plugin)   | Extracts and compiles catalogs, replaces macros with message IDs                     |
+| Paraglide (inlang)           | Compiles each message into its own tree-shakable function                            |
+| `vite-intlayer`              | Builds per-component dictionaries, then purges and minifies unused fields            |
+
+The shared payoff is twofold: the runtime message compiler stops shipping, and unused entries become statically removable. The shared cost is that your dev server and your CI both need the plugin, and a bare `tsc` or a non-Vite test runner will not see the generated output without extra configuration.
+
+vue-i18n is the clearest example of the first payoff. Without `@intlify/unplugin-vue-i18n` you ship a compiler that calls `new Function`, which is both bytes you did not need and a Content Security Policy problem.
+
+## SSR: never hold the locale in a module
+
+If you add SSR, whether through a framework or `vite-plugin-ssr`, the rule that matters is this: a module-level variable holding the current locale is shared across every concurrent request on that server process.
+
+```ts
+// Fine in a browser. A cross-request data leak on a server.
+export let currentLocale = "en";
+```
+
+Two users hitting the server at the same time will race, and one of them gets the other's language. It does not reproduce in development because you are the only request. Resolve the locale per request and pass it down explicitly, through context or through your framework's request-local storage.
+
+## Intlayer's Vite plugin
+
+Intlayer registers a single plugin that handles the dictionary build, dev-mode watching and the optimization pipeline.
+
+```ts fileName="vite.config.ts"
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [react(), intlayer()],
+});
+```
+
+Import rewriting, purge and minify are on by default. The two flags worth knowing live in `intlayer.config.ts`:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // drop content fields no component reads
+    minify: true, // rename content keys to short aliases
+  },
+};
+
+export default config;
+```
+
+Because content is declared per component rather than per locale file, the purge pass has a module graph to work against, which is what makes the removal safe. The trade is the one named above: the plugin is mandatory everywhere the code is compiled, including CI and test runners. Details in [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md).
+
+## Common mistakes
+
+- **`{ eager: true }` on a glob you meant to lazy-load.** Works in dev, ships everything in prod.
+- **Trusting folder structure to produce chunks.** Rollup follows imports, not directories. Measure the build.
+- **Restarting the dev server to see a translation change.** That is a missing HMR handler, not normal.
+- **Putting the locale in `define`.** You have just committed to one build per language.
+- **Module-level locale state with SSR.** Cross-request leak that never appears locally.
+- **Benchmarking the dev server.** Unbundled modules tell you nothing about the bundle.
+
+## Going further
+
+- [Bundle optimization: purge, minify and what reaches the browser](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md)
+- [Benchmark reports across frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
+- [Configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [Set up Intlayer with Vite and React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react.md)
+- [Drop-in i18next compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/i18next.md)
+- [React i18n: how the provider model works](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/react.md)
+- [Vue i18n: how it works and where it hurts](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/vue.md)
+- [Per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md)