语言包的结构设计有严格规范：必须采用扁平化结构，键名需严格对齐，路径统一设置为 locales/zh.json 格式，HTTP 响应头需配置为 application/json，data-i18n 属性还需区分后缀（placeholder/title/alt），lang 属性需按照 BCP 47 标准同步更新并遍历所有子元素。缺少一个下划线，整页文案都可能无法显示。

JSON语言包如何组织才能避免键名错位或加载失败

键名无法对应、某个语言的文案完全空白、加载后部分文字未更新——这些问题通常源于 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属性如何标记才能覆盖所有文本场景

仅给

添加属性，结果 placeholder、title、alt 全部未更新——这不是 JS 遗漏，而是 HTML 标记不完整。

需区分两种情况：textContent 类内容（

、、）直接使用 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 的元素（如

、

），将其 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 节点不会被自动扫描。
真正困难的并非编写几行 JS 替换文字，而是确保每个 lang 属性、每个 data-i18n- 后缀、每个 JSON 键名都严丝合缝——缺少一个下划线，整页文案就可能消失。