json语言包必须扁平化（如{"home.title": "首页"}）、键名严格对齐、路径统一为locales/zh.json等、http头设application/json，且data-i18n需区分后缀（placeholder/title/alt），lang属性须按bcp 47标准同步更新并遍历子元素。
JSON语言包怎么组织才不会键名错位或加载失败
键名对不上、某个语言文案全白、加载后部分文字没变——这些问题90%出在JSON结构或路径上。不是JS写错了，是语言包本身没对齐。
- 每个语言一个文件，路径固定为
locales/zh.json、locales/en.json，别用i18n/zh-CN.json这种不一致路径 - 所有JSON必须扁平结构：不允许嵌套对象，
{"home": {"title": "首页"}}是错的；正确写法是{"home.title": "首页"} - 所有文件字段名（key）必须完全一致：哪怕
ja.json里某句还没翻译，也要保留"home.title": ""，否则JS查不到key就留空 - HTTP响应头必须含
Content-Type: application/json，Nginx或Vercel静态托管默认支持，但某些老旧内网服务器可能返回text/plain，导致response.json()静默失败
data-i18n属性怎么打标才能覆盖全部文本场景
只给<h1 data-i18n="welcome"></h1>加属性，结果placeholder、title、alt全没变——这不是JS漏了，是你HTML没标全。
-
textContent类内容（<p></p>、<button></button>、<label></label>）用data-i18n - 属性类内容必须带后缀：
data-i18n-placeholder、data-i18n-title、data-i18n-alt，不能指望data-i18n自动猜 -
value属性不处理（表单输入值属于用户数据，不是界面文案），但label文字必须标data-i18n - 含HTML结构的文案（如“请阅读服务条款”）需用
innerHTML替换，对应语言包里的值必须是可信HTML片段，不能带用户输入内容，否则XSS
切换语言时document.documentElement.lang为什么必须同步改
文字替换了，但屏幕阅读器还在用中文读英文页面，字体渲染异常，标点间距不对——问题不在翻译逻辑，而在lang属性没更新到位。
-
document.documentElement.lang只影响根节点，子元素的lang属性不会继承，浏览器和辅助技术按每个元素自己的lang决定行为 - 切换时必须遍历所有已设
lang的元素（比如<p lang="en"></p>、<pre class="brush:php;toolbar:false;" lang="bash"></pre>），把它们的lang也改成当前语言码，除非明确要保留原语言 - 语言码必须符合BCP 47标准：
zh-Hans可以，zh_CN或chinese会被忽略，导致fallback失败 - 更新前用
window.scrollY记录位置，更新完立刻window.scrollTo()，否则DOM重排会跳回顶部
fetch加载语言包时容易踩的坑有哪些
本地开发一切正常，上线后部分用户语言包加载失败、控制台静默无报错——大概率是fetch被拦截或fallback没兜住。
- 不要用
await fetch('./locales/' + lang + '.json')裸写，必须包在try/catch里，且catch中要显式console.error和fallback到en.json - IE11不支持
dataset驼峰访问，查data-i18n要用getAttribute('data-i18n')兜底 - URL参数
?lang=ja优先级高于localStorage，但navigator.language返回zh-CN时，应截取主语言码zh再查zh.json，避免因zh-CN.json不存在而fallback失败 - 动态插入的DOM（弹窗、AJAX表格行）插入后必须立即调用翻译函数，否则
data-i18n节点不会被自动扫描
lang属性、每个data-i18n-后缀、每个JSON键名都严丝合缝——差一个下划线，整页文案就可能消失。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
