必须逐元素显式设置lang属性并同步更新所有data-i18n对应属性，仅改document.documentElement.lang无效；需遍历所有含lang元素和data-i18n节点，手动触发翻译，动态DOM插入后立即处理，语言包加载须校验MIME与状态并设fallback。
lang 属性必须逐层显式设置，不能只改 documentElement
只执行 document.documentElement.lang = 'zh-HK'，页面上 90% 的文本仍按旧语言渲染——标点间距错乱、字体回退失效、屏幕阅读器读错语音。浏览器和辅助技术不继承 lang，而是逐个检查每个元素自身的 lang 属性。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 所有含文本的语义化标签（
<h1></h1>、<p></p>、<section></section>、<footer></footer>）都必须显式写lang，值与当前激活语言包一致 - 已有明确语言用途的元素（如
<pre class="brush:php;toolbar:false;" lang="bash"></pre>、<blockquote lang="ja"></blockquote>）切换主语言时保留原lang，不覆盖 -
<script></script>和<style></style>内部加lang无效，直接删掉 - 切换语言时，需遍历
document.querySelectorAll('[lang]')并逐个赋值，不能只动根节点
data-i18n 必须覆盖所有可翻译属性，不只是 textContent
只给 <button>提交</button> 加 data-i18n="btn_submit"，但漏掉 placeholder 或 aria-label，会导致表单提示、无障碍播报始终是英文，且无任何报错提示。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 每个要翻译的元素至少有一个基础
data-i18n键；若含placeholder，额外加data-i18n-placeholder；同理data-i18n-title、data-i18n-alt -
value属性一般不翻译（属于用户输入数据），但<input type="submit">和<button></button>的显示文案需处理（它们可能用textContent或value渲染） -
<select></select>的<option></option>需单独遍历，不能靠父级data-i18n推导 - 含 HTML 结构的文案（如“请阅读服务条款”）必须用
innerHTML替换，但语言包里对应值必须是可信纯 HTML 片段，否则有 XSS 风险
动态插入的 DOM 必须手动触发翻译，不会自动监听
AJAX 加载的弹窗、分页表格新行、懒加载模块插入后，里面的 data-i18n 标记只是字符串——没调用翻译函数，就不会变成目标语言文本，控制台也无报错。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 在
appendChild()或insertAdjacentHTML()后立即调用翻译函数（如i18n.translate(el)），不能依赖全局扫描 -
<svg></svg>内的<text></text>节点需单独识别，普通遍历会跳过 - SSR 首屏 HTML 中，若
data-i18n出现在 DOM 深度 >6 层（如嵌套 7 个<div>），多数轻量翻译脚本会截断遍历，导致漏翻译——应改用 <code><main></main>、<section></section>等语义标签中断深度语言包加载必须带校验和 fallback，不能硬编码或裸 fetch
把语言包直接写进 JS，或只用
fetch('./locales/en-US.json')不检查响应状态，会导致构建体积膨胀、404 静默失败、MIME 类型错误（如返回text/plain）时解析崩溃。实操建议：
立即学习“前端免费学习笔记（深入）”；
- 路径统一为
./locales/${lang}.json，例如./locales/zh-Hans.json、./locales/en-US.json - 加载必须用
fetch()+try/catch，内部检查response.ok和response.headers.get('content-type')?.includes('application/json') - fallback 顺序：先试完整 BCP 47 码（
zh-HK），再截主语言（zh），最后兜底到内置默认对象（非空字符串占位） - 不要依赖
localStorage决定首次加载语言——用户可能清过缓存；优先用document.documentElement.lang（SSR 注入）或navigator.language
- 路径统一为
