lang属性必须逐层同步更新所有含lang的元素，data-i18n需覆盖placeholder/title/aria-label等可翻译属性，dom嵌套不得超过6层，动态内容插入后须立即翻译，语言包须用fetch校验加载并按bcp 47 fallback。
lang属性必须逐层同步，不能只改documentElement
只执行document.documentElement.lang = 'en'是无效的。浏览器和屏幕阅读器按每个元素自身的lang属性决定标点间距、字体回退链、语音播报语言——不是继承值。你看到的“顿号变逗号”“alt仍读英文”“<title></title>没更新”，本质都是旧lang还在生效。
实操建议：
- 切换前先收集所有已设
lang的元素：document.querySelectorAll('[lang]') - 对每个匹配元素执行
el.lang = newLang，包括<p lang="zh"></p>、<pre class="brush:php;toolbar:false;" lang="bash"></pre>、<blockquote lang="ja"></blockquote> - 表单控件如
<input placeholder="搜索">的placeholder文本也依赖其父容器或自身lang，不能跳过
data-i18n必须覆盖所有可翻译属性，不只是textContent
很多团队只给<button>提交</button>加data-i18n="btn_submit"，漏掉placeholder、title、aria-label等，结果输入框提示始终是英文，辅助技术播报错位。
实操建议：
- 每个要翻译的元素至少有一个基础
data-i18n键；含placeholder就额外加data-i18n-placeholder；同理data-i18n-title、data-i18n-alt -
value属性一般不翻译（属于用户输入数据），跳过处理；但<label for="email">Email</label>的文字必须标记，且for属性要与id严格对应 - 含HTML结构的文案（如“请阅读使用条款”）必须用
innerHTML替换，语言包里对应值要是可信纯HTML片段，否则有XSS风险
DOM嵌套超6层会导致data-i18n漏扫描
当data-i18n标记嵌套在<div><div><div><div><div><p data-i18n="msg"></p></div></div></div></div></div>这类纯CSS堆叠结构里时，遍历逻辑常因深度截断或性能阈值跳过最内层节点——语言切换后文字没变，控制台却无报错。
实操建议：
- 用浏览器Elements面板右键 → “Reveal in Elements panel”，手动数路径层级：从
到目标data-i18n元素，必须≤6 - 把冗余
<div>替换为语义标签：<code><main></main>、<section></section>，天然中断嵌套深度，同时支持i18n工具自动识别作用域 - 动态插入内容（如弹窗、表格行）必须在
appendChild()后立即调用翻译函数，不能依赖全局扫描 - 语言包路径统一为
./locales/${lang}.json，例如./locales/zh-HK.json、./locales/en-US.json - 加载必须用
fetch()，外层包try/catch，内部检查response.ok和response.headers.get('content-type')?.includes('application/json') - fallback顺序：先试完整BCP 47码（如
zh-HK），再截主语言（zh），最后退到默认语言（en）
语言包加载必须用fetch+校验，不能硬编码或内联JSON
把语言包直接写进JS里，会导致构建产物体积膨胀、无法按需加载、热更新困难；用XMLHttpRequest老式写法又容易忽略HTTP状态码和MIME类型校验，遇到404或服务器返回text/plain MIME时静默失败。
实操建议：
data-i18n，而是确保它被扫到、被替换成正确语言、且所有关联属性（lang、placeholder、alt）同步更新——这三者缺一不可，漏掉任意一个，无障碍、SEO、用户感知都会出问题。
