HTML国际化如何通过JSON文件管理翻译字段

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">加属性，结果placeholder、title、alt全没变——这不是JS漏了，是你HTML没标全。

• textContent类内容（<p>、<button>、<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">、<pre lang="bash">），把它们的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键名都严丝合缝——差一个下划线，整页文案就可能消失。