国际化包必须与构建流程深度耦合，否则import会失败、require报错；vite中应通过动态import()按需加载src/locales/下的语言json文件，由构建工具自动解析打包，不可直接script引入node_modules源码。
HTML 工程化环境下，国际化包不是“装进 node_modules 就能用”的东西——它必须和构建流程深度耦合，否则 import 会失败、require 会报错、语言包根本加载不进来。
国际化包必须走构建链路，不能直接 script 引入
常见错误是把 i18next 或 vue-i18n 的源码文件（比如 node_modules/i18next/index.js）直接塞进 <script src="..."></script>。浏览器会立刻报 Uncaught ReferenceError: require is not defined 或 Cannot find module 'fs'。
- npm 包默认面向 Node.js，依赖 CommonJS 或 ESM 模块系统，浏览器原生不支持裸模块名（如
import i18next from 'i18next'） - 即使你用
type="module"，浏览器也只认相对/绝对路径，不认识包名 - 真正能直接
<script></script>引入的，只有 CDN 上打包好的 UMD 版本（如https://cdn.jsdelivr.net/npm/i18next@23.11.0/i18next.min.js），且它会挂载到window.i18next - 工程化项目中，你应该让构建工具（Vite/Webpack）自动解析
import并打包语言资源，而不是手动拼路径
Vite 项目里怎么管国际化包和语言资源
Vite 是目前 HTML 工程化中最轻量又最贴合现代需求的选择，它天然支持 .html 入口和动态导入，适合管理多语言资源。
- 安装时用
npm install i18next i18next-browser-languagedetector（运行时依赖），不要加-D——它们最终要进浏览器 - 语言包建议放在
src/locales/下，按结构组织：zh-CN.json、en-US.json，避免散落在各处 - 不要手动 import 所有语言包，改用动态
import()+setLng实现按需加载：import(`./locales/${lng}.json`) - Vite 的
build.rollupOptions.external别误把i18next外部化，否则生产环境会找不到模块 - 如果用了
vite-plugin-pwa或缓存策略，注意locales/目录要被包含进 precache，否则切换语言后资源 404
Webpack loader 类工具（如 miao-i18n）的坑在哪
像 miao-i18n 这类 loader 的核心价值是“零侵入提取中文”，但它对工程结构非常敏感，稍不注意就失效。
- loader 必须放在
rules数组最顶部，因为 Webpack loader 是从下往上执行的；如果上面有babel-loader先转义了字符串，miao-i18n就提取不到原始中文 - 它依赖
exclude: /node_modules/，但如果你的组件库（比如自研 UI 组件）放在src/components之外，又没显式 include，就会漏提 - 生成的
$i18n是全局变量，和i18next实例不兼容——不能混用，否则t()函数行为不可预测 - 它用 MD5 生成 key，导致相同中文在不同文件里 key 一致，看似省事，但一旦文案微调（比如加个空格），key 就变，旧翻译全失效，反而增加维护负担
语言包更新后如何避免部署遗漏
最常被忽略的是：语言包变更不会触发构建缓存失效，Vite/Webpack 默认只看 JS/TS 文件改动。
- 在 Vite 中，把
src/locales/**/*加进defineConfig({ server: { watch: { ignored: [] } } })不够，得靠import.meta.glob或插件监听 - 推荐做法：在
vite.config.js里用build.watch或自定义插件，当locales/下文件变化时，强制清空.vite缓存目录 - CI/CD 流程中，加一行校验脚本：
jq -S . src/locales/*.json | sha256sum，对比前后哈希，防止语言包未提交却合并上线 - 如果用 JSON5 或 YAML 写语言包（为支持注释），记得配好对应 loader，否则构建时报
Unexpected token
真正麻烦的从来不是“怎么装包”，而是语言资源和代码构建的边界在哪里——这个边界模糊了，就容易一边改文案一边等构建失败，一边切语言一边看到空白文本。工程化里的国际化，本质是让资源变更成为构建的一部分，而不是开发完成后再补作业。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
