语言包json文件必须键名严格一致、结构扁平，新增/删除文案需在所有语言文件中同步增删空字符串键，修改时全局搜索批量替换，且http响应头须为application/json。
语言包 JSON 文件怎么改才不翻车
每次文案变更，必须同步修改所有语言包里对应 key 的值，不能只改中文、漏掉英文或日文。键名（如 form.submit）必须严格一致，结构扁平——嵌套层级越深，JS 查找越慢，也越容易漏字段。
常见错误现象：en.json 里删了 "nav.about"，但没在 zh.json 和 ja.json 中补上空字符串 "nav.about": ""，结果切换到英文时该位置直接空白；或者键名大小写不统一（btn_submit vs btnSubmit），导致查不到。
- 新增文案：先在所有语言包中加键，值设为空字符串，再逐个填内容
- 删除文案：保留键，值设为空字符串，避免运行时报错或留白
- 修改文案：用搜索工具（如 VS Code 全局搜索）查所有语言文件中该 key，批量替换
- 服务器返回 JSON 时，HTTP
Content-Type必须是application/json，否则fetch()可能静默失败
HTML 页面里哪些地方必须手动更新 data-i18n
不是所有文本都会被自动翻译。只有显式打了 data-i18n 或其变体的节点才会参与更新。漏标 = 永远显示旧文案。
必须标记的包括：<h1></h1>、<p></p>、<button></button>、<label></label>、<legend></legend> 等可见文本容器；但仅加 data-i18n 还不够——placeholder、title、alt 这些属性需额外加后缀，比如 data-i18n-placeholder="search_hint"。
-
value属性跳过处理（表单输入值属于用户数据，不翻译） - 含 HTML 结构的文案（如“请阅读使用条款”）要用
innerHTML渲染，且语言包中值必须是可信 HTML 片段（防 XSS） -
<script></script>、<style></style>、<pre class="brush:php;toolbar:false;"></pre>内部不加data-i18n—— 这些节点不参与文本渲染 - 动态插入的 DOM（弹窗、AJAX 表格行）插入后必须立即调用翻译函数，不会自动监听
切换语言后页面状态为什么丢了
只执行 document.documentElement.lang = 'ja' + 批量更新 textContent，会导致表单输入值清空、滚动位置跳回顶部、日期选择器语言没变、屏幕阅读器仍读旧语言——因为这些状态和行为不依赖根节点 lang，而是各自独立。
- 表单
input、textarea的value不动，只更新placeholder和label - 更新前用
window.scrollY记录位置，更新完用window.scrollTo(0, y)恢复 - 所有已初始化的
Intl.DateTimeFormat/Intl.NumberFormat实例必须重建，不能复用 - 遍历所有带
lang属性的元素（如<p lang="en"></p>），把它们的lang值也同步更新，否则辅助技术无法正确识别
本地开发调试时怎么快速验证语言切换
别等部署后才测。本地启动 HTTP 服务（如 npx http-server），用浏览器开发者工具模拟不同语言环境，比改系统设置快得多。
- 在 Console 手动执行
localStorage.setItem('preferred-lang', 'ja')，刷新页面看是否加载ja.json - 临时覆盖
navigator.language：在 Console 运行Object.defineProperty(navigator, 'language', { value: 'zh-HK' })，再触发初始化逻辑 - 检查 Network 面板，确认加载的是
./locales/zh-HK.json还是 fallback 到zh.json，避免路径拼错 - 打开 Accessibility 面板，检查关键元素是否已带正确
lang属性，而不仅是根节点
data-i18n 标记漏了、某个 lang 属性没同步、或者某条翻译 key 在某个语言包里被悄悄删掉——这些错误不会报 JS 错，只会让用户看到空白或乱码，而且很难被测试覆盖到。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
