DOM深度超6层会导致多语言页面“漏翻译”，因遍历逻辑截断或性能阈值跳过最内层data-i18n节点，造成语言切换后部分文字未更新且无报错。
为什么 DOM 深度超 6 层会让多语言页面“漏翻译”
不是所有元素都能被遍历到。当 data-i18n 标记嵌套在 <div><div><div><div><div><p data-i18n="msg"></p></div></div></div></div></div> 这类纯 CSS 堆叠结构里时，爬虫和 JS 遍历逻辑都可能因深度截断或性能阈值跳过最内层节点——结果是中文页正常，切换英文后那段文字仍显示中文，且控制台无报错。
常见错误现象：
- 语言切换后部分按钮/提示文字没变，但
document.querySelectorAll('[data-i18n]').length返回的数量比预期少 - SSR 渲染的首屏 HTML 中，
data-i18n元素在body下第 7 层才出现，而服务端 i18n 初始化脚本只扫描前 6 层
解决思路：
- 用浏览器 Elements 面板右键 → “Reveal in Elements panel”，手动数路径层级：从
body到目标data-i18n元素，必须 ≤6 - 把冗余
div替换为语义标签：<main></main>、<section></section>、<article></article>天然中断嵌套深度，同时支持 i18n 工具自动识别作用域 - 动态插入内容（如弹窗、表格行）必须在
appendChild()后立即调用翻译函数，不能依赖全局扫描
lang 属性必须逐层同步，不能只改 documentElement
只执行 document.documentElement.lang = 'en' 是无效的。屏幕阅读器、字体渲染引擎、标点间距规则都依赖每个元素自身的 lang 属性，而不是继承值。你看到的“闪动”或语音错读，本质是旧 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-placeholder单独处理 - 第三方组件（如日期选择器）若未监听
lang变更，需显式调用其 locale 设置方法，例如flatpickr.set('locale', 'en')
JSON 语言包加载失败时 fallback 不等于“不报错”
fetch 失败静默吞掉、键缺失留空、BCP 47 语言码解析错位——这些都会导致线上页面局部空白，但控制台未必抛异常。
关键检查点：
- HTTP 响应头必须含
Content-Type: application/json，否则response.json()抛Unexpected token - 语言包结构必须扁平且字段对齐：
en.json有"btn_submit": "Submit"，zh.json就不能缺这个 key，哪怕填"" - fallback 顺序要严格：先试
zh-HK→ 再zh→ 最后en；用navigator.language直接取值不可靠，隐私模式下可能是und - 加载时加
try/catch并 fallback 到默认语言对象（非空对象），避免undefined.key导致整个翻译函数崩溃
SSR/CSR 混合场景下 lang 和 data-i18n 的初始化时机冲突
Next.js 或 Nuxt 页面首次渲染时，若服务端输出的 HTML 已带 data-i18n，但客户端 JS 在 hydration 前就执行了翻译逻辑，会把 SSR 渲染的文字覆盖成默认语言——用户看到的是“闪一下再变英文”。
正确做法：
- 服务端必须注入两个关键信息：
document.documentElement.lang和预加载的语言包 JSON 字符串（如window.__I18N_DATA__ = {...}） - 客户端初始化时优先读
window.__I18N_DATA__，不存在才 fetch；且翻译函数应在DOMContentLoaded后、React/Vue hydrate 前执行 - 避免在
useEffect或mounted钩子中触发全量翻译——此时 DOM 已被框架接管，直接操作可能破坏响应式绑定 - 动态路由页面（如
/product/[id]）需在服务端根据 URL path 解析语言，而非仅靠 cookie 或 header
data-i18n 元素离 body 不得超过 5 层，CI 脚本用 Puppeteer 实时验证。 
