所有用户可见静态文本节点必须显式添加data-i18n属性并赋值为语言包键名，JS仅识别该属性；placeholder、option等需单独标记，script等不可见节点无需添加。
data-i18n 属性怎么打才不漏文本
所有用户可见的静态文本节点，必须显式加 data-i18n，值为语言包里的键名，比如 "header_title" 或 "form_email_required"。JS 不会猜 class、id 或 innerText——它只认这个属性。
-
<h1 data-i18n="welcome">欢迎</h1>✅ 有效 -
<input placeholder="邮箱地址" data-i18n-placeholder="form_email">✅ 替换 placeholder -
<button data-i18n="submit_btn">提交</button>✅ 推荐统一用textContent更新 -
<select data-i18n="country_select"><option>中国</option></select>❌ 错误：每个<option>必须单独标，如<option data-i18n="country_china">中国</option> -
<script>console.log("error");</script>❌ 不渲染为可见文本，加了data-i18n无意义
JSON 语言包结构和加载失败怎么兜住
语言包必须扁平、键名一致、路径可预测，否则查不到 key 就留白——用户看到的是空格或原始键名，不是“加载中”。
- 每个语言一个文件：
locales/zh-CN.json、locales/en-US.json，内容全是顶层键值对：{"login_btn": "登录", "header_title": "欢迎"} - 缺失翻译也要保留键：
"nav_help": ""或"nav_help": "[未翻译]"，避免 JS 查找返回undefined - fetch 失败必须 fallback：
try/catch包住fetch('./locales/' + lang + '.json')，捕获TypeError: Failed to fetch或 404 - fallback 优先级建议：先试完整码（
zh-HK），再截主语言（zh），最后退到内置默认对象（硬编码英文） - 服务端返回 JSON 时，响应头必须含
Content-Type: application/json，否则response.json()可能静默失败
为什么 document.documentElement.lang 改了但屏幕阅读器还是读中文
因为浏览器和辅助技术按每个元素自己的 lang 属性决定语音引擎、字体 fallback 和标点行为——不是继承来的。根节点改了，已渲染的子节点完全不受影响。
- 页面初始化时，必须设
document.documentElement.lang = 'zh-CN'（注意：用zh-CN，别用zh_CN或chinese） - 切换语言后，要遍历所有已有
lang属性的元素（如<p lang="ja">…</p>），判断是否需同步更新 - 明确要保留原语言的（如代码块、引文），则跳过；局部多语言内容必须显式写内联
lang：<code lang="bash">npm install</code>
动态插入的 DOM 怎么保证翻译生效
DOM 插入后不会自动触发翻译，JS 不监听新增节点。必须在插入完成的第一时间手动调用翻译函数，否则 data-i18n 仍是纯字符串。
立即学习“前端免费学习笔记（深入）”；
- AJAX 加载弹窗：
modalEl.innerHTML = responseHtml后，立即执行translateNode(modalEl) - 分页表格每页新
<tr>插入后，需对新行调用querySelectorAll('[data-i18n]')并逐个替换 - SVG 内嵌文本（如
<text data-i18n="download">下载</text>）需单独识别SVGTextElement类型做处理 - 表单控件的
option文字不能靠父级data-i18n推断，必须遍历select[data-i18n] option，查语言包中对应数组字段（如"country_select.options"）
lang 属性的粒度控制——它不是装饰性标签，而是直接影响标点宽度、连字规则、字体回退链和语音朗读方式的语义信号。哪怕只漏掉一个 <footer lang="zh-CN">，某些屏幕阅读器就会把顿号读成英文间距，而你根本看不到报错。 
