最轻量方案是用data-i18n标记+JSON语言包+localStorage记忆选择；需同步更新文案、document.documentElement.lang及子元素lang、存储状态、fallback机制和动态属性（如placeholder）。
直接用 data-i18n 标记 + JSON 语言包 + localStorage 记忆选择，是最轻量、可控、且不依赖构建工具的方案。硬编码文案或只改 document.documentElement.lang 都会出问题——前者改一次全站重发，后者屏幕阅读器和字体渲染根本没反应。
怎么给 HTML 元素打翻译标记
所有要动态换语言的文本节点，必须显式加 data-i18n 属性，值是语言包里的键名。不能只靠 class 或 id 推断，JS 没法自动猜。
-
data-i18n只作用于元素自身文本内容（textContent），如需替换placeholder、title、alt等属性，得额外加data-i18n-placeholder这类带后缀的属性 - 表单控件、按钮、SVG 文本等都得单独处理，比如
<input data-i18n-placeholder="search_hint"> - 别在
<script></script>或<pre class="brush:php;toolbar:false;"></pre>里乱加data-i18n——这些节点通常不渲染为可见文本，加了也白加 - 如果某段文字含 HTML 结构（比如带链接的提示语），用
innerHTML替换，但要确保语言包里对应值是可信的纯 HTML 片段，避免 XSS
为什么必须同时改 document.documentElement.lang 和子元素 lang
只改根节点的 lang，对已渲染的子元素完全无效。浏览器和屏幕阅读器按每个节点自己的 lang 属性决定语音、字体回退、标点间距——不是继承来的。
- 页面加载时，应根据当前选中的语言码（如
zh-Hans）设置document.documentElement.lang = 'zh-Hans' - 所有明确夹带其他语言的内容（如英文术语、代码块、引文），必须单独写
lang="en"或lang="bash"，不能指望全局覆盖 - 切换语言后，除了更新文本，还得遍历所有带
lang的元素，把非根节点的lang值也同步更新（比如多语言博客里一段日文引用，得跟着主语言切） - BCP 47 标准必须遵守：
zh-CN可以，zh_CN或chinese会被忽略甚至触发 fallback 失败
JSON 语言包怎么组织才不容易翻车
结构扁平、键名一致、文件路径固定，是避免加载失败和 key 错位的核心。别图省事把所有语言塞进一个大对象里。
立即学习“前端免费学习笔记（深入）”；
- 每个语言一个文件：
locales/zh.json、locales/en.json、locales/ja.json，内容全是顶层键值对，不要嵌套层级 - 所有文件键名必须严格一致，哪怕某语言暂时没翻译，也要留空字符串或占位符，否则 JS 查不到 key 就留白
- 加载失败时必须有 fallback：fetch 失败或 key 不存在，一律退到
en或你设定的主语言 JSON，否则整页文案消失 - 避免在 JSON 里放需要运行时计算的内容（如用户昵称、时间格式），这类得用插值语法（如
"hello {name}"）+ JS 运行时替换，别硬塞进静态语言包
用户选了语言，刷新后为啥又变回中文
因为没读 localStorage，或者读了但没在 DOM 渲染前就执行翻译逻辑——导致初始 HTML 用的是默认文案，JS 后置替换造成闪屏甚至失败。
- 页面最顶部的
<script></script>就该读localStorage.getItem('lang')，没值再 fallback 到navigator.language或'zh' - 翻译函数必须在
DOMContentLoaded触发前完成，或者用document.write注入初始语言包（慎用），否则 DOM 已渲染完毕，再改textContent会触发重排 - 下拉菜单或按钮切换时，除了调用翻译函数，必须立刻
localStorage.setItem('lang', 'en')，别等异步加载完再存——网络慢时用户点完没反应，会再点一次 - 服务端渲染场景下，这个逻辑得挪到服务端做，客户端只负责补动态内容；否则 SEO 文案和首屏看到的语言可能不一致
最容易被忽略的是：语言切换不是“换文案”一件事，而是文案 + lang 属性 + 存储状态 + fallback 机制 + 动态属性支持（placeholder/title）五件事必须同步到位。漏掉任意一环，用户就会遇到语音朗读错乱、输入框提示不显示、刷新后语言重置、或者整页空白。
