html-webpack-plugin多语言配置需循环创建实例，每个实例指定带语言后缀的filename、独立模板参数及lang属性，确保构建产物中html lang动态注入且可被html-validate校验。
HTML 国际化不是加个 lang 属性就完事，核心在于文本内容与 HTML 结构解耦，且必须让构建流程能识别、提取、注入多语言数据——否则本地跑得通，CI 里漏翻译、产物缺语言文件、SEO 的 hreflang 标签没生成，全是线上事故。
html-webpack-plugin 多语言输出怎么配才不翻车
别用单个插件实例硬塞所有语言参数，它不支持运行时动态切换；也别手写多个 new HtmlWebpackPlugin() 手动罗列，维护成本爆炸。正确姿势是循环语言配置 + 显式控制输出路径和模板参数：
- 语言配置必须抽成独立 JS/JSON 文件（如
locales/config.js），导出对象：{ en: { title: "App", lang: "en" }, zh: { title: "应用", lang: "zh-CN" } } - Webpack 配置里用
Object.keys(locales).map()动态 push 插件实例，每个实例的filename必须带语言后缀（如index.${lang}.html），否则所有语言会覆盖写入同一个文件 -
templateParameters只传当前语言对象，不要传整个 locales —— 模板里${title}就能直接取值，避免模板内写${locales[lang].title}这种耦合逻辑 - 模板中
<html lang="${lang}">必须存在，且值来自templateParameters.lang，不能写死或靠 JS 后续改 —— Lighthouse 和爬虫读的是静态 HTML
为什么 html-validate 总报 “attr-req-lang” 错误却不想关规则
不是规则错了，是你没在构建阶段把 lang 值真正注入到最终 HTML 中。常见假成功场景：JS 在 DOM 加载后用 document.documentElement.lang = navigator.language 设置，但 html-validate 扫描的是构建产物原始 HTML 字符串，根本看不到 JS 行为。
- 检查构建后 HTML 源码，确认
<html lang="xx">是否真实存在且值正确（比如zh-CN而非zh） - 若用 html-webpack-plugin，确保
templateParameters里确实有lang字段，且模板中写了<html lang="${lang}"> - 若用 Vite +
vite-plugin-html，注意它默认不支持模板参数透传，得配合inject选项或改用vite-plugin-inspect调试实际注入内容 - 禁止在 .htmlvalidate.json 里把
attr-req-lang设为"off"来绕过 —— 这等于放弃 WCAG 2.1 SC 3.1.1，屏幕阅读器可能读错语言
CI 里怎么自动校验多语言 HTML 文件是否完整
光生成多语言 HTML 不够，得验证每份文件都包含对应语言的文本、hreflang 标签是否互指、关键元素（如 <title>）有没有被漏掉。手动检查等于没做。
立即学习“前端免费学习笔记（深入）”；
- 在 CI 的 lint job 里，用
npx html-validate --config .htmlvalidate.json src/templates/**/*.html扫描所有模板源文件，而非只扫构建产物 —— 模板错了，产物全错 - 加自定义脚本检查构建产物目录（如
dist/）下是否存在index.en.html、index.zh.html等预期文件，缺失则exit 1 - 用
grep -q 'hreflang="en"' dist/index.zh.html类似命令，验证每个语言页是否包含其他语言的<link rel="alternate" hreflang="xx">标签 - 避免用正则匹配中文文本（如
grep -q "我的应用" dist/index.zh.html），UTF-8 BOM 或编码混用会导致失败；改用iconv -f utf-8 -t utf-8//IGNORE预处理再查
最常被忽略的一点：语言包 JSON 文件本身没进构建依赖图。Webpack/Vite 默认不追踪 require('./locales/en.json') 这类动态路径，改了翻译内容不触发重构建。必须显式配置 watchOptions 或用 import.meta.glob（Vite）确保语言文件变更能触发 HTML 重新生成。
