最稳的方式是为每种语言启动一个 HtmlWebpackPlugin 实例，每个实例注入对应语言的 templateParameters 并设置 filename 语言后缀；templateParameters 需解构扁平键值、含 BCP 47 格式 lang 字段，且 <html lang="<%= lang %>"> 必须同步注入；动态插入内容需手动调用 translateNode 处理 data-i18n 元素；键名推荐 domain.section.key 格式，统一小写点分隔。
html-webpack-plugin 多实例注入语言文件
直接改 document.documentElement.lang 不会生成多语言 HTML 文件，Webpack 构建阶段必须把语言内容“编译进去”。最稳的方式是为每种语言启动一个 HtmlWebpackPlugin 实例，每个实例注入对应语言的 templateParameters。
常见错误是只配一个插件、靠 JS 运行时加载语言包——这属于客户端 i18n，不是构建时注入，无法服务端渲染，SEO 友好性归零。
- 每个实例的
filename必须带语言后缀，如index.zh-CN.html、index.en-US.html -
templateParameters里不要传整个 JSON 对象，而是解构后的扁平键值，比如{ title: '首页', submit: '提交' }，避免模板里写这类嵌套语法 - 模板中所有可翻译字段（
<title>、<h1>、placeholder）都得用模板语法显式引用，不能依赖 JS 后续替换 - 如果用了 EJS 模板，记得在
<html>标签上写lang="<%= lang %>"，否则 CSS 的html[lang="zh-CN"]规则不生效
lang 属性必须随语言文件同步注入
只往 templateParameters 里塞文案，却忘了设 <html lang="...">，会导致字体回退、标点间距、屏幕阅读器朗读全错。浏览器不看 JS 变量，只认 DOM 上真实的 lang 值。
错误现象：中文页面里顿号「、」显示成英文宽度，<pre lang="bash"> 里的代码被中文字体覆盖，<img alt="logo"> 的替代文本仍被读作英文。
立即学习“前端免费学习笔记（深入）”；
-
templateParameters中必须包含lang字段，且值严格符合 BCP 47，如zh-Hans、en-US，不能写zh或cn - 已有语义化子元素（如
<pre lang="sql">、<code lang="js">）要保留原lang，这是合法混排，别全局覆盖 -
<script>和<style>标签内禁止加lang属性，它们不参与文本渲染
动态插入内容的注入必须手动触发
Webpack 构建只处理初始 HTML 模板，AJAX 加载的弹窗、分页表格新行、懒加载模块里的文案不会自动翻译。这些 DOM 插入后，必须立刻调用翻译函数遍历其内部 data-i18n 元素。
典型漏掉场景：<modal> 打开后 <h2 data-i18n="modal_title"> 还是原始键名；分页请求返回的 <tr> 行里 data-i18n 完全没变；SVG 内嵌的 <text> 标签被忽略。
- 封装一个
translateNode(node)函数，支持识别SVGTextElement类型并更新textContent - 对
select[data-i18n]要特殊处理：查语言包中"xxx.options"数组，再逐个更新option.textContent - 避免用
innerHTML替换整个节点——会清空事件监听器和已初始化的组件状态
i18n 键名设计影响工程化维护成本
键名不是越短越好，也不是越深越好。键名结构决定语言包拆分粒度、协作效率和翻译平台对接能力。扁平键名（如 login.submit）比纯 ID（如 btn123）更易维护，但比模块化嵌套（如 form.login.submit）更难做按域加载。
容易踩的坑：键名含空格或特殊字符导致 JSON 解析失败；用中文当键名（"登录按钮": "Login"）让前端开发者崩溃；键名与 DOM ID 强绑定，一旦改 ID 就断翻译。
- 推荐格式：
[domain].[section].[key]，例如header.nav.home、form.login.password - 所有键名统一小写 + 英文点号分隔，禁用下划线、大驼峰、中文、emoji
- JSON 语言包按功能模块拆分（
common.json、dashboard.json），构建时用Promise.all并行加载，首屏不卡
document.documentElement.lang、所有子元素的 lang、表单控件的 placeholder、SVG 文本、动态模块的 innerHTML、以及 Intl 格式化实例全部同步到位——漏掉任意一环，用户看到的就是混合语言的残缺界面。 
