data-i18n必须覆盖所有可翻译节点及属性，不能只处理textcontent；需为placeholder、title、alt等显式添加带后缀的data属性，lang须逐元素设置，动态dom需手动触发翻译，语言包加载须fallback校验。
data-i18n 必须覆盖所有可翻译节点和属性，不能只扫 textContent
只给 <button>提交</button> 加 data-i18n="btn_submit"，但漏掉 placeholder、title、alt、aria-label，切换后输入框提示、图片替代文本、工具提示仍卡在旧语言——这是最常见的维护断裂点。
-
data-i18n只负责元素自身的textContent；其他属性需显式用带后缀的 data 属性：如data-i18n-placeholder、data-i18n-title、data-i18n-alt -
value属性一般不翻译（属用户输入数据），但<label for="email">Email</label>中的文本必须标记，且for值要与对应input的id严格一致 - 含 HTML 结构的文案（如“请阅读服务条款”）必须用
innerHTML替换，语言包里对应值要是可信纯 HTML 片段；否则直接插入有 XSS 风险 - 别在
<script></script>、<style></style>、<pre class="brush:php;toolbar:false;"></pre>内部加data-i18n—— 这些节点不渲染为可见文本，JS 替换无效
lang 属性必须逐个设置，不能只改 document.documentElement.lang
只执行 document.documentElement.lang = 'zh-Hans'，页面视觉上像切换了，但屏幕阅读器仍读英文、中文顿号间距错乱、<pre class="brush:php;toolbar:false;" lang="bash"></pre> 字体被中文字体覆盖——因为浏览器和辅助技术按每个元素自身的 lang 属性判定行为，不是继承来的。
- 所有含文本的语义化容器（
<h1></h1>、<p></p>、<section></section>、<footer></footer>）都应显式带lang属性，值与当前语言包一致 - 已有明确多语言意图的元素（如
<pre class="brush:php;toolbar:false;" lang="bash"></pre>、<code lang="sql">）切换时保留原lang，这是合法混排，不是 bug -
<title></title>和<meta name="description">不继承根节点lang，必须单独更新（通常通过 JS 动态写入） -
<script></script>和<style></style>内部设lang无意义，不参与文本渲染
JSON 语言包加载必须校验 MIME 类型和 fallback 链路
语言包加载失败时页面留白或部分文案消失，往往不是代码逻辑问题，而是 fetch() 静默失败：服务器返回 404、HTTP 状态码非 2xx、或 Content-Type 是 text/plain 而非 application/json。
- 路径统一用
./locales/${lang}.json，支持 BCP 47 完整码（如zh-HK），不要硬编码成./zh.json - fetch 外层必须
try/catch，内部检查response.ok和response.headers.get('content-type')?.includes('application/json') - fallback 顺序必须是：先试完整码（
zh-HK）→ 再截主语言（zh）→ 最后退到默认语言（en） - 所有语言包结构必须扁平、键名完全对齐；某语言暂未翻译，也要保留键并设为空字符串（
"btn_submit": ""），否则查不到 key 就跳过
动态 DOM 插入后必须手动触发翻译，不会自动监听
AJAX 加载的弹窗、分页表格新行、懒加载模块插入后，里面带 data-i18n 的元素仍是原始键名，不会自动变成对应语言文本——DOM 插入和事件绑定是两件事，i18n 没有 MutationObserver 自动监听机制。
- 每次插入新节点后，立即调用翻译函数（如
translateElement(newNode)或translateAll(newNode.querySelectorAll('[data-i18n]'))） - 第三方组件（如日期选择器）若含内嵌文本，需在其初始化后手动触发翻译，或监听其内部 DOM 渲染完成事件
- 避免在插入前就预渲染带
data-i18n的 HTML 字符串；应在插入后、挂载完成时再处理，否则事件监听器可能丢失 - 表单控件、SVG 文本、按钮文字都要单独加标记，不能指望父容器一统到底
data-i18n-title 漏写了，或者某段 <p lang="ja"></p> 在切换时被误覆盖。这些细节一旦松动，无障碍、SEO、字体回退就全跟着失效。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
