data-i18n标记必须覆盖所有可翻译属性，不只是textContent；placeholder、alt、title、aria-label等需显式加对应后缀，value属性一般不翻译，lang属性须全量同步，语言包字段须对齐，HTML注入须严格过滤防XSS。
data-i18n标记必须覆盖所有可翻译属性，不只是textContent
只给 <h1 data-i18n="home.title"> 加属性，但漏掉 <input placeholder="Search">，切换语言后 placeholder 还是英文——这不是漏翻译，是标记没打全。
常见错误现象：alt、title、aria-label、placeholder 这些属性不会被 textContent 更新逻辑触达，必须显式加后缀：
data-i18n-placeholder="search_hint"data-i18n-alt="user_avatar"data-i18n-title="tooltip_info"data-i18n-aria-label="close_button"
value 属性一般不翻译（属于用户输入数据），但 <button> 和 <input type="submit"> 的显示文案建议用 textContent 更新，避免意外提交英文值。
JSON语言包加载失败时页面留白，怎么兜底
fetch() 加载 ./locales/zh.json 失败，或 key 查不到（比如 "nav_home" 在 zh.json 里缺失），默认行为是留空——用户看到空白按钮或标题，不是“未翻译”，而是“挂了”。
立即学习“前端免费学习笔记（深入）”；
必须在加载和查找环节都加 fallback：
- fetch 外层用
try/catch，失败时降级到en.json或内置默认对象 - 查 key 时用
langPack[key] ?? langPack.fallback ?? "MISSING_KEY"，不能直接langPack[key] - 所有语言包字段必须对齐：某语言暂未翻译也要保留键，设为空字符串
"btn_submit": ""，否则查不到就undefined - HTTP 响应头
Content-Type: application/json必须正确，否则response.json()静默抛错
切换语言时页面闪动或语音读错，根源在lang属性没同步
只执行 document.documentElement.lang = "zh-Hans"，但页面里已有 <p lang="en"> 或 <pre lang="bash">，屏幕阅读器仍按旧 lang 朗读，中文顿号间距错、英文字体回退失效——这不是 JS 没跑完，是浏览器根本不认根节点继承。
切换时必须做两件事：
- 遍历所有带
lang属性的元素（document.querySelectorAll("[lang]")），除明确要保留原语言的（如<pre lang="bash">），其余全部设为当前语言码 - 确保所有新插入的动态 DOM（AJAX 弹窗、分页表格行）插入后立即调用翻译函数，否则
data-i18n标记只是字符串，不会自动生效 - BCP 47 格式必须严格：用
zh-Hans，不用zh_CN或chinese，后者会被忽略甚至触发 fallback 失败
外部文本注入与国际化混用时 XSS 风险高发点
用 <script src="output.txt"> 加载含变量声明的文本文件，再把内容塞进 <p>，如果这个文本来自 CMS 或日志生成，且语言包里又用了 innerHTML 渲染带链接的文案（如 "terms_link": "请阅读<a href="https://www.php.cn/link/07fd2295ead5c4d45892fe3ab22a846a">服务条款</a>"），XSS 就藏在中间。
安全边界必须划清：
- 纯文本内容一律用
textContent注入，杜绝 HTML 解析 - 含结构的文案（如带
<strong>或链接）必须走innerHTML，但语言包对应值要是可信纯 HTML 片段——不能拼接用户输入，也不能执行 JS - 动态注入的 HTML 片段（如弹窗内容）必须过
DOMPurify.sanitize()，哪怕来源是内部系统 -
<script>和<style>内部禁止写data-i18n——它们不参与渲染，JS 替换无效，还可能被误解析
最易被忽略的是：语言包里的 HTML 片段一旦含用户可控内容（比如评论摘要），就必须过滤；而外部 .txt 文件若被攻击者篡改，let text = '...' 就成了执行入口——这两条链路的安全水位必须一致。
