lang属性必须逐元素设置，data-i18n需覆盖所有可翻译属性，动态插入DOM后须手动触发翻译，三者缺一不可。
lang 属性必须逐元素设置，不能只改 document.documentElement.lang
只执行 document.documentElement.lang = 'zh-Hans'，页面文字不会自动变、屏幕阅读器仍读英文、中文顿号间距错乱、<pre lang="bash"> 里的代码字体被中文字体覆盖——浏览器和辅助技术根本不看根节点 lang，而是逐个检查每个含文本元素自身的 lang 属性。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 所有含文本的语义化标签（
<h1>、<p>、<section>、<footer>、<label>）都得显式写lang，值与当前语言包一致，比如<p lang="zh-Hans">欢迎</p> - 已有明确语言用途的元素（如
<pre lang="bash">、<code lang="sql">）切换语言时保留原lang值，这是合法混排，不是 bug -
<script>和<style>内部写lang没意义，它们不参与文本渲染
data-i18n 必须覆盖所有可翻译属性，不只是 textContent
只给 <button>提交</button> 加 data-i18n="btn_submit"，但漏掉 placeholder 或 aria-label，结果输入框提示仍是英文、屏幕阅读器播报错位——data-i18n 默认只替换文本内容，对属性完全无效。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 每个要翻译的元素至少有一个基础
data-i18n键；含placeholder就额外加data-i18n-placeholder；同理data-i18n-title、data-i18n-alt、data-i18n-aria-label -
value属性一般不翻译（属于用户输入数据），但<button>和<input type="submit">的显示文案建议统一走textContent更新 - 含 HTML 结构的文案（如“请阅读服务条款”）必须用
innerHTML替换，且语言包里对应值要是可信纯 HTML 片段，否则有 XSS 风险
动态插入的 DOM 必须手动触发翻译，不会自动监听
AJAX 加载的弹窗、分页表格新行、懒加载模块插入后，里面的 data-i18n 标记只是字符串，不会变成对应语言文本——DOM 插入和事件监听是两件事，i18n 工具不会自动遍历新节点。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 弹窗打开后，在
appendChild或insertAdjacentHTML之后立即调用翻译函数，例如translateElement(modalEl) - 分页获取新
<tr>后，对这批新节点做一次querySelectorAll('[data-i18n]')并逐个替换 - 避免在
setTimeout里延迟翻译——竞态下可能漏掉或重复执行
UTF-8 编码与 BOM 必须全局统一，否则 <meta charset="UTF-8"> 会失效
<meta charset="UTF-8"> 写在 <head> 开头也没用，如果 HTML 文件本身是 GBK 编码、或带 BOM 的 UTF-8、或编辑器保存时选了 “UTF-8 with BOM”，浏览器实际解析出的字符就是乱码——HTML 解析器只读前 1024 字节找 <meta charset>，BOM 或错误编码会让它直接 fallback 到系统默认（Windows 是 GBK）。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 所有源文件（.html / .css / .js / .json）统一保存为 UTF-8 无 BOM；VS Code 保存时选 “UTF-8”，别选 “UTF-8 with BOM”
- 用十六进制查看器确认文件开头：UTF-8 无 BOM 应是
3C 21 64 6F...（即<!），带 BOM 是EF BB BF 3C 21... - HTTP 响应头
Content-Type: text/html; charset=UTF-8必须与</meta>一致；Nginx 配置里写charset utf-8;，Apache 用AddDefaultCharset UTF-8
最易被忽略的是：lang 属性粒度、data-i18n 属性覆盖范围、动态节点翻译时机这三者必须同步更新，缺一不可。一个没设 lang 的 <p> 即使文本翻对了，标点和字体回退还是错的；一个漏掉 data-i18n-placeholder 的输入框，切换语言后提示永远卡在英文；一段没手动触发翻译的 AJAX 表格行，永远显示原始 key。
