data-i18n标记不会自动触发翻译，必须手动调用翻译函数遍历更新textcontent及placeholder、title等带后缀属性，并同步设置每个元素的lang属性，动态插入节点需立即单独翻译。
data-i18n 标记的 DOM 批量更新必须手动触发
页面加载后，data-i18n 属性只是静态标记，不会自动变成对应语言文本。哪怕你已加载了 zh.json，所有带 data-i18n 的元素仍显示原始键名（如 home.title），除非你显式调用翻译函数遍历并填充。
常见错误现象：切换语言后，新插入的弹窗、AJAX 加载的表格行、动态创建的按钮文字全都是键名；点击语言按钮没反应，是因为只改了语言包变量，没执行 DOM 更新逻辑。
- 必须在语言包加载成功后，立即调用类似
translatePage(lang)的函数，且该函数要遍历全部匹配[data-i18n]的元素 - 对
placeholder、title、alt、aria-label等属性，需额外检查data-i18n-placeholder等后缀，不能只处理textContent - 动态插入的节点（如
document.createElement('div')）插入 DOM 后，必须立刻调用translateNode(newEl, lang)，否则标记无效
lang 属性必须逐个同步，不能只改 document.documentElement.lang
只设置 document.documentElement.lang = 'zh-Hans' 是无效操作。浏览器和屏幕阅读器依据每个元素自身的 lang 属性决定标点宽度、字体回退、语音朗读方式——不继承父级。未显式设 lang 的 <p></p> 或 <section></section> 仍按默认语言渲染，顿号变英文间距、中文标点被撑开、语音引擎读错语种。
容易踩的坑：把 lang 当成 CSS 类，以为加在根节点就全局生效；或误以为 data-i18n 会自动补上 lang 属性。
- 翻译函数里必须同时更新两类东西：文本内容（通过
textContent/innerHTML） + 元素lang属性（如el.lang = 'zh-Hans'） - 已有
lang的特殊元素（如<pre class="brush:php;toolbar:false;" lang="bash"></pre>）应跳过，保留其原值，这是合法的多语言混排场景 - 更新前用
window.scrollY记录位置，更新后立即window.scrollTo(0, scrollY)，否则页面会跳顶
语言包加载失败时 fallback 必须分层且可调试
fetch ./locales/zh-Hans.json 失败时，直接 fallback 到 en.json 很危险——可能因网络问题、路径拼写错误、HTTP Content-Type 不是 application/json 导致静默失败，整个页面变空白键名。
真实项目中，用户看到的是 btn_submit 而不是 “提交”，根本不知道哪出错了。
- fallback 顺序必须严格：先试完整 BCP 47 码（
zh-Hans）→ 再截主语言（zh）→ 最后退到默认（en），每步都加catch日志 - 语言包字段必须完全对齐：所有 JSON 文件含相同键，暂未翻译也设为空字符串
"btn_submit": ""，避免查不到 key 就留白 - 服务端返回 JSON 时，
Content-Type: application/json缺一不可，否则response.json()抛错
动态内容区域（如弹窗、分页表格）需要独立翻译上下文
主页面翻译完，不代表新内容自动适配。AJAX 加载的弹窗 HTML 片段、分页接口返回的 <tr> 行、懒加载模块里的按钮，里面的 <code>data-i18n 标记全是死的——它们不在初始 DOM 中，翻译函数启动时根本遍历不到。
性能影响：如果每次插入都全量重跑 translatePage()，会重复扫描整个文档，尤其页面大时卡顿明显。
- 推荐做法：为动态区域提供轻量翻译入口，例如
translateFragment(fragment, lang)，只遍历传入的 fragment 节点 - 分页表格每页数据返回后，在
insertAdjacentHTML插入前，先用translateFragment(trList, currentLang)处理 - 弹窗打开时，等
innerHTML设置完毕，再调用translateNode(modalEl, currentLang)，而非监听DOMSubtreeModified（已废弃且性能差）
lang 属性的逐个同步和动态节点的即时翻译——这两处漏掉，国际化就只剩表面文字，失去可访问性与排版正确性。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
