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

作者：袖梨 2026-07-12

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节点不会被自动扫描