data-i18n值必须显式对应JSON扁平键名，如"nav_home"；仅匹配textContent，placeholder等需data-i18n-placeholder等后缀；键名全小写下划线，禁止嵌套；加载须try/catch+降级fallback。
data-i18n 属性怎么映射到 JSON 键名
映射不是自动推导，必须显式对齐：HTML 元素的 data-i18n 值（如 "nav_home"）直接作为 JSON 语言包里的键名去查。浏览器不认 class、id 或文本内容，只认这个属性值。
- 键名必须全小写+下划线，避免空格、点号、大写字母——
"navHome"或"nav.home"在多数轻量方案里会查不到 - 嵌套结构（如
{"menu": {"home": "首页"}}）不被原生支持；扁平键名"menu_home"才可靠 - 同一页面多个相同文案（比如五个“提交”按钮），可以共用一个键名，但得确保所有地方翻译一致，否则维护时容易漏改
- 若元素含 HTML 标签（如
<p data-i18n="terms_link">请阅读<a href="#">使用条款</a></p>），语言包对应值必须是已转义或白名单过滤的纯 HTML 字符串，否则innerHTML赋值会触发 XSS
JSON 语言包路径和加载失败怎么兜底
路径错、网络断、文件空、键缺失，任意一个环节出问题都会导致文案空白——这不是警告，是真实线上事故高频原因。
- 固定路径模板：
./locales/${lang}.json，例如zh-CN.json、en-US.json；别用动态拼接或相对路径跳转（如../i18n/en.json），构建或部署时容易断裂 -
fetch()必须包裹try/catch，且检查response.ok和response.headers.get('content-type')?.includes('application/json')，HTTP 200 返回 HTML 页面（如 404 页）会导致response.json()报错 - fallback 顺序不能只靠 try/catch 捕获异常：先试完整码（
zh-HK），再截主语言（zh），最后退到默认语言（en）；单靠localStorage.getItem('lang')不够，它可能存的是过期值 - 键不存在时，不要静默留空——至少 fallback 到英文键名本身（如显示
"nav_home"），方便定位漏翻译项
为什么不能把所有语言塞进一个 JSON 文件
看似省事，实则埋雷：键名对不齐、diff 差异难读、CI/CD 验证失效、翻译协作冲突率飙升。
- 多人并行翻译时，一个大 JSON 文件极易产生 git merge 冲突；分文件后，
zh.json和ja.json可完全隔离编辑 - CI 流程中可加校验脚本：遍历所有
.json文件，确保每个键在全部语言文件中都存在（哪怕值为空字符串），缺失即 fail - 前端加载时可并行
Promise.all([fetch('en.json'), fetch('zh.json')])，但运行时只用当前语言那一份；全塞一起反而要解析整个巨对象，浪费内存 - 服务端 SSR 场景下，按需读取单个语言文件也比解析全量 JSON 更快更稳
表单 placeholder/title/alt 怎么同步更新
data-i18n 默认只管 textContent，这些属性得单独打标，否则切换语言后输入框还是英文提示。
立即学习“前端免费学习笔记（深入）”；
- 必须用带后缀的属性：
data-i18n-placeholder、data-i18n-title、data-i18n-alt；不能复用同一个data-i18n值去猜该填哪 - 表单控件（
<input>、<select></select>、<textarea></textarea>）的value不翻译——它是用户输入数据，属于业务状态，不是界面文案 -
<label></label>文字必须标记data-i18n，但关联的for属性不用动；<option></option>的文本内容也要单独标，不能只标<select></select>容器 - 动态插入的表单（如 JS 弹窗里的登录框），插入 DOM 后必须立刻调用翻译函数，否则这些新节点永远不会被处理
document.documentElement.lang，对已有 <p lang="en"></p> 这类显式声明的节点完全无效——屏幕阅读器、字体回退、标点渲染全按旧值走。切换语言时，必须主动遍历并重置它们。 
