@intlayer/docs 9.4.1 → 9.4.3

package/blog/zh/is_vue-i18n_outdated.md

@@ -0,0 +1,338 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: 2026 年，vue-i18n 已经过时了吗？
+description: vue-i18n 在过去十年中一直是 Vue 和 Nuxt 的标准配置。但在我们的基准测试中，它却是主流框架中最庞大的 i18n 运行时。本文将探讨其深层原因。
+keywords:
+  - vue-i18n
+  - Intlayer
+  - 国际化
+  - i18n
+  - Vue
+  - Nuxt
+  - 打包体积
+  - 博客
+slugs:
+  - blog
+  - is-vue-i18n-outdated
+author: aymericzip
+---
+
+# 2026 年，vue-i18n 已经过时了吗？
+
+在 Vue 生态系统中，鲜有库能达到 `vue-i18n` 的普及度。自 Vue 2 时代起由 Kazupon 持续维护，它支撑着 `@nuxtjs/i18n`，几乎是多语言 Vue 应用的默认首选。
+
+然而，2026 年的基准测试得出了一个出人意料的数据：**在所有测试的前端框架中，`vue-i18n` 竟是最庞大的本地化运行时。**
+
+在基于 Vite + Vue 搭建的仅 31.5 KB 的空白初始项目中，引入 `vue-i18n` 后，单页平均 JavaScript 体积飙升至 **136.4 KB**，翻了 4 倍有余。
+
+为什么一个以轻量、灵动著称的框架，其配套的国际化工具却如此厚重？其纯运行时的传统模型在今天是否依然合理？
+
+<TOC/>
+
+## 核心观点
+
+**测试中体积最大的运行时：**
+
+在未载入任何翻译内容前，其基础体积即达 **24.3 KB（gzip 压缩后，未压缩约 83.2 KB）**，约是 `intlayer` 核心运行时（2.7 KB）的 **9 倍**。
+
+**单页开销增加 330%：**
+
+`vue-i18n` 让一个基础 Vue 页面从 31.5 KB 暴增至 136.4 KB。相比之下，Intlayer 仅为 59.3 KB，**单页体积减少了 56%**。
+
+**浏览器里附带编译器：**
+
+除非在打包配置中显式设置别名，否则 `vue-i18n` 默认会把一个功能完整的消息格式编译器打包进浏览器，用于在客户端实时解析文本。
+
+**维护节奏趋于平缓：**
+
+在过去的 12 个月里，`vue-i18n` 提交了约 259 次 commit，工作重心主要落在常规 Bug 修复与 Vue 新版本的被动兼容。
+
+**缺乏现代原生工具链：**
+
+缺乏官方提供的 Language Server (LSP)、面向 AI 的 MCP Server 或基于 CLI 的全自动化翻译支持。
+
+## 维护模式 vs. 现代工具生态
+
+| 仓库                  | Stars                                                                                                                                                  | 总 Commit 数                                                                                                                                                        | 年 Commit 数                                                                                                                                                       | 最近一次 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) |
+
+过去一年的产出：
+
+- `intlify/vue-i18n`：**259 次 commit**（Vue 3 与 Nuxt 的例行维护）。
+- `aymericzip/intlayer`：**4,343 次 commit**（持续投入编译器优化、LSP 语言服务以及深度 AI 集成）。
+
+[![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)
+
+久经考验的库往往代表稳定，但现代化前端开发已全面转向构建期 AST 转换、无用代码精简和 AI 赋能。受制于纯运行时的架构设计，旧模型较难自如融入这些革新。
+
+## 基于 Vite + Vue 的实测数据
+
+针对包含 10 个页面、10 种语言的 Vite + 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;"
+/>
+
+> 在真实浏览器中开启 gzip 压缩环境下测试。完整数据见 [Vue 基准测试文档](https://intlayer.org/zh/doc/benchmark/vue)。
+
+### 库本身的基础体积
+
+未引入任何翻译文本时客户端的空白开销：
+
+| 库                | Gzip 压缩后 | Minified 未压缩 |
+| ----------------- | ----------- | --------------- |
+| `vue-i18n@11.4.0` | 24.3 KB     | 83.2 KB         |
+| `intlayer@8.7.12` | **2.7 KB**  | **7.6 KB**      |
+
+仅 `vue-i18n` 运行时的体积就达到 **24.3 KB（gzip 压缩后）**，几乎相当于整个 Vue 核心库的大小。而 Intlayer 仅增加 **2.7 KB**。
+
+### 页面体积与数据泄漏分析
+
+| 配置            | 单页平均 JS (gz) | 跨语言泄漏 | 跨页面泄漏 | 平均组件大小 (gz) |
+| --------------- | ---------------- | ---------- | ---------- | ----------------- |
+| 基准（无 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**        |
+
+### 核心观察
+
+**比例增幅极其明显：**
+
+由于 Vue 基础框架非常小巧（约 31 KB），引入 `vue-i18n` 会使页面总体积直接跃升四倍多。
+
+**严重的跨路由文本泄漏：**
+
+在默认模式下，单个路由接收到的**翻译内容中有 90%** 实际上属于其他页面。Intlayer 通过静态剔除将该数据降低至 **0.0%**。
+
+**独立作用域组件体积过大：**
+
+由于词典数据在各个作用域中被重复复制，使用 `vue-i18n` 的局部组件平均体积高达 196 KB，而在 Intlayer 中仅为 **6.5 KB**。
+
+## 为什么 vue-i18n 如此沉重？
+
+### 打包进浏览器的 AST 编译器
+
+`vue-i18n` 内置了完整的消息格式编译器。复杂的复数规则、变量插值在客户端运行期间实时被转译成抽象语法树（AST）。
+
+要规避这一开销，开发者必须手动在打包器中为 `vue-i18n/dist/vue-i18n.runtime.esm-bundler.js` 配置别名，并借助 `@intlify/unplugin-vue-i18n` 实施预编译。但在实际工程中，这一步骤经常被遗漏。
+
+### 单体式功能捆绑
+
+`vue-i18n` 集成了日期和数字格式化工具、链式消息、传统 Options API 兼容垫片（`$t`、`v-t`）以及响应式 Proxy 逻辑。即便你的组件只是在 `<script setup>` 中读取普通字符串，也必须全盘加载。
+
+### 动态键名阻断 Tree-shaking
+
+由于 `"home.hero.title"` 在运行时动态求值，打包工具无法静态推测被使用的文本范围。多余的翻译内容不得不全部存留在包内。
+
+<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>
+
+[Intlayer 编译器](https://intlayer.org/zh/doc/compiler)能够准确识别访问了哪些属性，在生成客户端 bundle 之前剔除无用字段。具体解析请查阅[打包优化](https://intlayer.org/zh/doc/concept/bundle-optimization)。
+
+## 开发者体验对比
+
+### 分离式 JSON vs. 组件就近组织
+
+在 `vue-i18n` 中，翻译通常放在独立的 `locales/` 文件夹中。Intlayer 则支持把内容声明直接放置在组件文件同级：
+
+<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/zh.json"
+{
+  "hero": {
+    "title": "用每一种语言发布产品"
+  }
+}
+```
+
+```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",
+      zh: "用每一种语言发布产品",
+    }),
+  },
+} 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>
+
+移动或删除 `Hero.vue` 时，与其绑定的多语言声明文件也会一并同步处理。
+
+### 代码提示 vs. 严格完备性检查
+
+`DefineLocaleMessage` 能带来基于基准模式的代码补全，但无法验证多语言翻译的完备性。即使 `zh.json` 中遗漏了键，TypeScript 也不会阻止编译。
+
+在 Intlayer 中，多语言数据遵循严格校验机制。开启 [`strictMode`](https://intlayer.org/zh/doc/concept/configuration) 后，只要任意语言存在未翻译词条，构建流程便会即刻报错中断。
+
+### IDE 与 AI 辅助工具
+
+| 功能特性                  | `vue-i18n`             | Intlayer                                                         |
+| ------------------------- | ---------------------- | ---------------------------------------------------------------- |
+| **VS Code 扩展**          | 第三方插件 (i18n Ally) | ✅ [官方专属插件](https://intlayer.org/zh/doc/vs-code-extension) |
+| **Language Server (LSP)** | ❌ 无                  | ✅ [专属 LSP 服务](https://intlayer.org/zh/doc/lsp)              |
+| **AI MCP Server**         | ❌ 无                  | ✅ [内置 MCP Server](https://intlayer.org/zh/doc/mcp-server)     |
+| **AI Agent Skills**       | ❌ 无                  | ✅ [开箱即用 Skills](https://intlayer.org/zh/doc/agent_skills)   |
+| **可视化上下文 CMS**      | ❌ 无                  | ✅ [免费开源 CMS](https://intlayer.org/zh/doc/concept/editor)    |
+
+## 翻译流水线
+
+`vue-i18n` 没有提供内置的翻译命令。开发者通常必须将文件导出给第三方平台（如 Crowdin 或 Phrase）。
+
+Intlayer 提供了开箱即用的闭环工作流：
+
+**本地 AI 自动补全（`intlayer fill`）：**
+
+直接配合个人的 OpenAI、Anthropic、Mistral 或 Gemini API 密钥，自动补齐缺失词条。
+
+**自主托管的可视化 CMS：**
+
+集成 [Intlayer CMS](https://intlayer.org/zh/doc/concept/cms)，方便非技术人员直观修改文案，并直接以 Git 提交的形式落盘。
+
+**开源宽松授权：**
+
+全套组件均基于 Apache 2.0 协议发布。
+
+## 什么时候选用 vue-i18n 依然合适？
+
+<AccordionGroup>
+<Accordion header="长期运行的稳定 Nuxt 2/3 项目">
+
+若既有项目的路由层已与 `@nuxtjs/i18n` 深度强绑定，推倒重来的成本可能过高。
+
+</Accordion>
+<Accordion header="重度依赖特殊 ICU 特性">
+
+如需要高度定制的嵌套链接式消息或特殊的本地化格式规则。
+
+</Accordion>
+<Accordion header="轻量个人小项目">
+
+如果生产环境打包体积并不影响应用的核心使用体验。
+
+</Accordion>
+</AccordionGroup>
+
+## 如何改进我现有的 vue-i18n 配置？
+
+Intlayer 提供了平滑替换的兼容包，完整再现了 `vue-i18n` 与 `@nuxtjs/i18n` 的核心函数签名（`useI18n`、`$t`、`<i18n-t>`）。你无需重构模板或组合式函数（composables），即可无缝过渡到基于编译器的轻量级架构。
+
+只需运行单条命令即可完成集成：
+
+```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
+```
+
+该交互式 CLI 工具会自动完成以下工作：
+
+1. 安装 `@intlayer/vue-i18n` 或 `@intlayer/nuxt-i18n` 兼容包。
+2. 配置 Vite 或 Nuxt 打包别名（alias），使现有的导入语句和模板用法平滑路由至 Intlayer，之后便可直接从 `package.json` 中移除 `vue-i18n`。
+3. 立即激活语言服务器（LSP）诊断，从客户端包中剥离 24 KB 的运行时 AST 解析器，并开启本地 AI 自动化翻译流程，无需繁杂的工程重构。
+
+更多详细步骤请参考我们的专题文档：
+
+- **平滑兼容层：** 使用 [`vue-i18n` 兼容层](https://intlayer.org/zh/doc/compatibility/vue-i18n) 或 [`@nuxtjs/i18n` 兼容层](https://intlayer.org/zh/doc/compatibility/nuxtjs-i18n)，即可在保留旧有模板语法的同时享受现代构建优化。
+- **迁移指南参考：** 查阅迁移手册逐步将 JSON 转换为类型安全的字典配置：[从 vue-i18n 迁移](https://intlayer.org/zh/doc/migration/vue-i18n)、[从 @nuxtjs/i18n 迁移](https://intlayer.org/zh/doc/migration/nuxtjs-i18n)。
+- **混合使用方案：** 你也可以在运行时维持 `vue-i18n`，仅[将 Intlayer 与 vue-i18n 搭配使用](https://intlayer.org/zh/blog/intlayer-with-vue-i18n)，以低成本引入严格类型检查和本地 AI 翻译。
+
+使用免费的 [i18n SEO 分析器](https://intlayer.org/i18n-seo-scanner) 测量你当前应用的实际打包体积和内容泄漏情况：
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## 相关阅读
+
+- [Vue & Vite i18n 性能评测：深度对比报告](https://intlayer.org/zh/doc/benchmark/vue)
+- [vue-i18n 与 Intlayer 全方位对比](https://intlayer.org/zh/blog/vue-i18n-vs-intlayer)
+- [2026 年，next-intl 已经过时了吗？](https://intlayer.org/zh/blog/is-next-intl-outdated)
+- [编译型国际化与声明式架构优势剖析](https://intlayer.org/zh/blog/compiler-vs-declarative-i18n)

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

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Vite i18n：Glob 导入、分包与构建期文案处理"
+description: 探讨 i18n 中真正属于 Vite 特性的核心逻辑。使用 import.meta.glob 实现懒加载字典、为何按路由切分语言包常常失效、HMR 缺陷以及编译期插件机制。
+keywords:
+  - vite i18n
+  - import.meta.glob
+  - vite 代码分割
+  - 懒加载翻译
+  - vite 插件 i18n
+  - rollup chunks
+slugs:
+  - blog
+  - i18n-technologies
+  - build-tools
+  - vite
+author: aymericzip
+---
+
+# Vite i18n：真正属于 Vite 本身而非前端框架的技术内幕
+
+网络上大部分所谓的“Vite i18n”教程，本质上只是恰巧使用了 Vite 的 React 或 Vue 教程。本文聚焦于更底层的工程机制：字典是如何被导入的、Rollup 是如何对其分包的，以及你手写的懒加载为什么在实际生产中往往并不“懒”。
+
+## 目录
+
+<TOC/>
+
+## 静态导入是默认模式，且属于即时加载
+
+最直接的配置是在模块顶部静态导入每一个语言字典：
+
+```ts fileName="src/i18n.ts"
+import en from "./locales/en.json";
+import fr from "./locales/fr.json";
+import ja from "./locales/ja.json";
+```
+
+这会导致三个语言字典全部被打包进入口 Chunk 中，并在每个页面加载时强行推送给所有访问者。对于只有两种语言、一百来条文案的项目尚可接受；一旦扩展到十种语言，它就会变成打包产物中最严重的性能浪费。
+
+## `import.meta.glob` 与最容易配错的配置项
+
+Vite 的 Glob 导入功能是解决这一问题的常规手段：
+
+```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>;
+};
+```
+
+懒加载是默认行为：每个条目都是一个返回动态导入的函数，Rollup 会为每个文件单独输出一个独立 Chunk。而一旦加上 `{ eager: true }`，所有字典都会被内联并入当前模块中，与优化的初衷背道而驰：
+
+```ts
+// 所有语言全部硬塞进入口 Chunk 中（极力不推荐）：
+const catalogs = import.meta.glob("./locales/*.json", { eager: true });
+```
+
+其中的陷阱在于，这两种写法在本地开发环境中运行良好，因为 Vite 在开发模式下以非打包形式单独提供各模块。真正的差异只在 `dist` 产物中显现。请通过 `npx vite build && npx vite preview` 实际构建并检查入口 Chunk 究竟塞入了什么。
+
+## 按路由拆分语言包往往无法真正拆开
+
+这是一个经常让开发者感到意外的现象。你按照页面将字典拆散存放：
+
+```
+locales/en/home.json
+locales/en/checkout.json
+```
+
+若有两个不同的路由同时导入了 `checkout.json`，Rollup 就会将该文件提升为一个在两个页面之间共享的公共 Chunk。Rollup 的分包策略是由模块依赖图谱决定的，而不是依据你的目录结构：任何能从多个入口访问的模块都会被提升为公共依赖。新增第三个路由不会改变现状，而引入第四个路由时可能会导致完全不同的分包重组。
+
+因此，按路由切分语言包只有在模块导入图谱严格互不相交时才能成立。如果包体积是关键指标，请依靠可视化工具验证，而不是凭空假设：
+
+```bash
+npx vite build && npx vite-bundle-visualizer
+```
+
+若需要强行划定分包边界，可以使用 `build.rollupOptions.output.manualChunks`，但代价是必须长期手动维护。
+
+## 字典文件默认不支持热更新（HMR）
+
+修改一个组件代码，Vite 能够即时热替换页面模块。但当你修改 `locales/fr.json` 时，根据导入方式的不同，页面很可能毫无反应。动态导入的 JSON 文件缺乏原生的 HMR 边界，导致模块图谱无法知晓应当如何让下游消费组件失效并重新渲染。
+
+许多开发者每改一个文案就习惯性地重启开发服务器，却不知道这本可以通过工程化手段避免。这一职责应当由 i18n 插件承担：它需要监听 HMR 更新事件，并将最新的文案消息动态推送到运行中的应用中。在技术选型时，务必关注对应的 Vite 插件是否妥善支持了该能力。
+
+## `define` 会在构建期将语言环境直接写死
+
+在构建时固化默认语言环境是很有吸引力的做法：
+
+```ts fileName="vite.config.ts"
+export default defineConfig({
+  define: {
+    __DEFAULT_LOCALE__: JSON.stringify(process.env.LOCALE ?? "en"),
+  },
+});
+```
+
+`define` 是在编译阶段执行的纯文本替换。构建期间存在的具体值就是最终产物中固化的值，这迫使你必须针对每种语言单独执行一次完整构建。这种策略虽然完全合法（例如 Angular 官方的原生 i18n 便采用此方案），但若你的诉求是通过一次构建部署服务所有语言，这绝非良策。
+
+对于需要随用户请求动态变化的数据，切勿放进 `define`，而应在运行时动态求值。
+
+## 将文案解析工作前置到构建阶段
+
+这个生态中所有成熟的技术选型最终都走向了同一个方向：彻底停止在浏览器中解析文案格式。
+
+| 插件                         | 前置到构建阶段的处理工作                                              |
+| :--------------------------- | :-------------------------------------------------------------------- |
+| `@intlify/unplugin-vue-i18n` | 将 vue-i18n 文案编译为渲染函数（仅发布纯运行时轻量包）                |
+| Lingui (宏 + 插件)           | 提取并编译字典，将宏调用转换为精简的消息 ID                           |
+| Paraglide (inlang)           | 将每条文案编译为独立的、支持 Tree-shaking 的函数                      |
+| `vite-intlayer`              | 构建组件级字典，自动清除（purge）未使用的字段并进行键名压缩（minify） |
+
+这样能带来双重收益：运行时的文案编译器不再打包进产物中，且未被引用的字段可以通过静态分析直接剔除。代价是开发服务器和 CI 都必须挂载对应的插件，而在脱离 Vite 环境直接运行裸 `tsc` 或测试工具时需要配置额外的类型支持。
+
+vue-i18n 是最典型的例子：如果不加 `@intlify/unplugin-vue-i18n`，打包产物中将包含一个调用 `new Function` 的解析器，不仅徒增包体积，还会破坏严格的 CSP（内容安全策略）限制。
+
+## SSR：严禁在模块顶级作用域缓存语言状态
+
+如果你接入了 SSR（无论是通过上层框架还是通过 `vite-plugin-ssr`），必须死守这条铁律：模块级变量中保存的当前语言环境，会被该 Node.js 进程下的所有并发请求共享。
+
+```ts
+// 在浏览器中安全无虞。在服务端则是跨请求的数据污染漏洞：
+export let currentLocale = "en";
+```
+
+两个并发访问服务器的用户会陷入竞态条件，导致其中一人收到另一种语言的渲染结果。在本地单人调试时绝不会复现该 Bug。必须按请求独立求值，并通过上下文（Context）或框架自带的请求级上下文隔离存储显式透传。
+
+## Intlayer 的 Vite 插件
+
+Intlayer 提供了一个一体化的 Vite 插件，统一处理字典构建、开发环境热监听以及打包优化流程：
+
+```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()],
+});
+```
+
+模块导入重写、无用文案清理（purge）和键名压缩（minify）默认开启。核心控制项收敛在 `intlayer.config.ts` 中：
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // 剔除任何组件都未读取的内容字段
+    minify: true, // 将文案键名重命名为紧凑的短别名
+  },
+};
+
+export default config;
+```
+
+由于文案是伴随组件就近声明而非集中在单一庞大文件中，清除流程可以直接依赖模块依赖图谱，从而实现安全的死代码消除。权衡在于：任何编译代码的环境（包括 CI 与测试框架）都必须配置该插件。详情见 [包体积优化指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md)。
+
+## 常见错误
+
+- **对本意为懒加载的 Glob 配置了 `{ eager: true }`。** 本地运行良好，上线后所有语言全量打包。
+- **误以为目录结构天然等同于 Chunk 边界。** Rollup 追踪的是导入依赖图，而非文件目录。
+- **为了看到文案修改而反复重启开发服务器。** 这是缺少 HMR 支持的表现。
+- **在 `define` 中固化语言环境。** 迫使项目走向“一种语言一次构建”的模式。
+- **在 SSR 场景中将语言环境保存在模块顶级作用域。** 引发难以排查的跨请求并发污染。
+- **在开发服务器上评估包体积与性能。** 未经打包的单文件模块无法代表生产环境的构建产物。
+
+## 深入阅读
+
+- [包体积优化：清除、压缩以及实际传输给浏览器的产物分析](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md)
+- [跨框架性能基准测试报告](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)
+- [配置参考手册](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [在 Vite + React 项目中集成 Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+react.md)
+- [i18next 兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/i18next.md)
+- [React i18n：Provider 架构的内在原理](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/list_i18n_technologies/frameworks/react.md)
+- [Vue i18n：运作机制与技术局限](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/list_i18n_technologies/frameworks/vue.md)
+- [组件就近 i18n 与集中式 i18n 的架构对比](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/per-component_vs_centralized_i18n.md)

package/blog/zh/list_i18n_technologies/frameworks/angular.md

@@ -23,8 +23,6 @@ author: aymericzip
 
 在当今互联的世界中，提供多种语言的网站可以显著扩大您的覆盖面并改善用户体验。对于使用 Angular 的开发人员来说，实现国际化 (i18n) 对于有效管理翻译，同时保持应用程序结构、SEO 和性能至关重要。在本文中，我们将探讨各种 i18n 方法, 从 Angular 的内置解决方案到流行的第三方库, 帮助您确定最适合您项目的方案。
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 什么是国际化 (i18n)？
 
 国际化，通常称为 i18n，是设计和准备您的应用程序以支持多种语言和文化背景的过程。在 Angular 中，这涉及到配置您的应用程序，使得文本、日期、数字，甚至 UI 布局可以无缝适应不同的区域设置。妥善打下这一基础可以确保将来集成翻译时保持组织有序和高效。

package/blog/zh/list_i18n_technologies/frameworks/react-native.md

@@ -25,8 +25,6 @@ author: aymericzip
 
 ---
 
-![i18n 说明](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 什么是国际化（i18n）？
 
 国际化或 i18n 涉及对应用程序的结构设计，以便它可以轻松适应不同的语言、区域格式和文化规范。在 React Native 中，i18n 包括处理按钮和标签的字符串，以及根据用户的区域格式来格式化日期、时间、货币等。适当准备的 React Native 应用程序使您能够无缝集成其他语言和特定于区域的行为，而无需进行大量重构。

package/blog/zh/list_i18n_technologies/frameworks/react.md

@@ -25,8 +25,6 @@ author: aymericzip
 
 ---
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 什么是国际化（i18n）？
 
 国际化，缩写为 i18n，是设计和准备您的网站以支持多种语言和文化背景的过程。在 React 中，这意味着设置您的应用程序，以便字符串、日期格式、数字格式，甚至布局都可以轻松适应来自不同地区的用户。为 i18n 准备您的 React 应用程序为干净地集成翻译和其他本地化功能奠定基础。

package/blog/zh/list_i18n_technologies/frameworks/svelte.md

@@ -25,8 +25,6 @@ author: aymericzip
 
 ---
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 什么是国际化 (i18n)？
 
 国际化，通常缩写为 i18n，是设计和构建应用程序的过程，以便它可以轻松适应各种语言、地区和文化习俗。在 Svelte 中，这通常意味着设置翻译字符串、本地化日期、时间和数字，并确保用户界面可以在不同语言环境之间动态切换，而无需进行重大代码重写。

package/blog/zh/list_i18n_technologies/frameworks/vue.md

@@ -25,8 +25,6 @@ author: aymericzip
 
 ---
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 什么是国际化 (i18n)？
 
 国际化 (i18n) 是为多个语言和文化习俗准备软件应用程序（或网站）的做法。在 Vue.js 生态系统中，这包括确定如何将文本、日期、数字、货币和其他可本地化元素适配到各种区域。通过从一开始就设置 i18n，您可以确保一个有序、可扩展的结构，以便添加新语言和处理未来的本地化需求。

package/blog/zh/what_is_internationalization.md

@@ -20,8 +20,6 @@ author: aymericzip
 
 # 什么是国际化 (i18n)? 定义与挑战
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 理解国际化 (i18n)
 
 **国际化**，通常缩写为 **i18n**，是设计和准备一个应用程序以支持多种语言、文化和地区惯例的过程**而不**对代码库进行重大更改。i18n这个名称源于“国际化”这个词中**i**和**n**之间有18个字母这一事实。

package/dist/cjs/common.cjs

@@ -77,19 +77,42 @@ const getFileMetadataRecord = async (files, locale = defaultLocale) => {
 	}
 	return await record;
 };
+/**
+* Flattens front-matter slugs into the URL segments they produce.
+*
+* `relativeUrl` is built by joining the slugs with `/`, so a slug holding a
+* slash — `"@intlayer/babel"` — yields more URL segments than the array holds
+* entries. A requested path, split on `/`, could then never be matched against
+* the raw array, and the page resolved to nothing.
+*
+* @param slugs - Front-matter slugs, or the segments of a requested path.
+* @returns One entry per URL segment, empty segments dropped.
+*/
+const toUrlSegments = (slugs) => slugs.flatMap((slug) => slug.split("/")).filter(Boolean);
+/**
+* Tells whether a file answers a requested slug path.
+*
+* @param fileMetadata - Metadata of the candidate file.
+* @param requestedSegments - URL segments asked for, already flattened.
+* @param strict - Rejects files owning segments beyond the requested ones.
+* @returns `true` when the file matches the request.
+*/
+const matchesRequestedSegments = (fileMetadata, requestedSegments, strict) => {
+	const fileSegments = toUrlSegments(fileMetadata.slugs ?? []);
+	if (strict && fileSegments.length !== requestedSegments.length) return false;
+	return requestedSegments.every((segment) => fileSegments.includes(segment));
+};
 const getFileMetadataBySlug = async (files, slugs, locale = defaultLocale, strict = false) => {
-	const slugsArray = Array.isArray(slugs) ? slugs : [slugs];
+	const requestedSegments = toUrlSegments(Array.isArray(slugs) ? slugs : [slugs]);
 	const filesMetadata = await getFileMetadataRecord(files, defaultLocale);
-	let fileMetadataArray = Object.values(filesMetadata).filter((fileMetadata) => slugsArray.every((slug) => fileMetadata.slugs?.includes(slug)));
-	if (strict) fileMetadataArray = fileMetadataArray.filter((fileMetadata) => fileMetadata.slugs.length === slugsArray.length);
+	const fileMetadataArray = Object.values(filesMetadata).filter((fileMetadata) => matchesRequestedSegments(fileMetadata, requestedSegments, strict));
 	if (locale !== defaultLocale) return await Promise.all(fileMetadataArray.map(async (fileMetadata) => await getFileMetadata(files, fileMetadata.docKey, locale)));
 	return fileMetadataArray;
 };
 const getFileBySlug = async (files, slugs, locale = defaultLocale, strict = false) => {
-	const slugsArray = Array.isArray(slugs) ? slugs : [slugs];
+	const requestedSegments = toUrlSegments(Array.isArray(slugs) ? slugs : [slugs]);
 	const filesMetadata = await getFileMetadataRecord(files, defaultLocale);
-	let fileMetadataArray = Object.values(filesMetadata).filter((fileMetadata) => slugsArray.every((slug) => fileMetadata.slugs?.includes(slug)));
-	if (strict) fileMetadataArray = fileMetadataArray.filter((fileMetadata) => fileMetadata.slugs.length === slugsArray.length);
+	const fileMetadataArray = Object.values(filesMetadata).filter((fileMetadata) => matchesRequestedSegments(fileMetadata, requestedSegments, strict));
 	return await Promise.all(fileMetadataArray.map(async (fileMetadata) => {
 		return await getFile(files, fileMetadata.docKey, locale);
 	}));