HTML国际化不是仅加lang和data-i18n，必须统一管理所有可读文本、禁用innerHTML渲染、语义化结构支持RTL、资源与构建流程耦合校验。
HTML 项目做国际化（i18n）不是加个 lang 属性、套几层 data-i18n 就算完事的。真实项目里，债务往往藏在 DOM 结构松散、文本硬编码散落各处、语义标签被忽略、甚至用 JS 拼接 HTML 渲染多语言内容这些地方——它们不会报错，但会让后续新增语言、切换 RTL、接入屏幕阅读器的成本翻倍。
DOM 结构不稳导致 i18n 插件失效
很多团队用 i18next 或 vue-i18n，但发现翻译键值对更新后，部分文案没变，或切换语言时布局错乱。根本原因常是 DOM 节点层级被 JS 动态打乱，比如：
- 用
innerHTML直接插入带翻译占位符的字符串，绕过了框架的响应式更新机制 - 组件内多个
v-if/ngIf分支各自调用$t('key')，但 key 命名不统一（btn_submitvssubmit_btn），导致提取工具漏掉一半 -
aria-label或title属性里写死英文，没走翻译管道
建议：所有可读文本必须通过统一翻译函数注入；禁用 innerHTML 渲染含 i18n 的内容；用 axe 扫描验证每个 aria-* 属性是否绑定到有效翻译键。
硬编码文本分散在模板、JS、CSS 三处
一个按钮文案可能同时出现在：index.html 里的静态 <button>Save</button>、utils.js 中的错误提示 console.error('Failed to save')、styles.css 里的伪元素内容 ::after { content: 'Click here'; }。这类文本无法被提取工具捕获，人工补漏效率极低。
立即学习“前端免费学习笔记（深入）”；
使用 Puppeteer + Chrome 将 HTML 渲染为中文 PDF，自动处理图表等待、Tab 展开、动画、测高、白边消除、防分页，适用于看板、报表、网页和交互图表转 PDF。
- HTML 模板中禁止出现任何非空文本节点，全部替换为
{{ $t('save_btn') }}或等效语法 - JS 中所有用户可见字符串必须经
t()函数包裹，包括alert()、throw new Error()等场景 - CSS 伪元素内容一律移出，改用 data 属性 + JS 注入，或直接交由组件模板控制
否则每次新增语言，都要 grep 全库、逐个比对、手动补 key，且极易遗漏。
RTL 支持靠 CSS hack 而非语义化结构
为支持阿拉伯语或希伯来语，有些项目直接给 body 加 dir="rtl"，再用一堆 margin-right: auto、text-align: right 强行翻转布局。结果是：
- 表单控件（如
<input type="number">）光标位置异常 - 日期/数字格式未同步适配（如
2026-07-08应为٠٨-٠٧-٢٠٢٦） - 图标方向（如箭头、关闭叉）没随文本流翻转
正确做法是：用 dir 控制整体流向，但所有布局依赖 start/end 逻辑属性（如 margin-inline-start），图标用 [dir="rtl"] .icon-arrow::before 单独定义；数字和日期交由 Intl.DateTimeFormat 和 Intl.NumberFormat 处理，不硬编码格式字符串。
多语言资源未与构建流程耦合
翻译 JSON 文件放在 /locales 下，但没人检查它是否被实际引用。上线后才发现 zh-CN.json 里缺了 37 个 key，而前端只显示空字符串或 fallback 英文——用户看到的是 “” 或 “Submit”，不是“提交”。
- CI 流水线中加入校验步骤：对比所有源码中出现的
$t('xxx')调用，确保每个 key 在所有语言文件中都存在（可用i18next-parser提取 + 自定义脚本比对） - 构建时启用
missingKeyHandler，让缺失 key 抛出警告而非静默 fallback - 禁止在生产环境使用
returnObjects: true或嵌套对象作为翻译值，避免运行时解析开销和类型失控
最易被忽略的一点：i18n 债务不是“翻译没做完”，而是“结构没为多语言设计”。DOM 不语义、文本不集中、流向不抽象——这些才是拖垮后续所有语言扩展的根本瓶颈。
