最轻量可行路径是用data-i18n标记+外部JSON语言包+同步更新document.documentElement.lang；需为所有可翻译文本节点显式添加data-i18n，属性值如"nav_home"，placeholder/title/alt等需加后缀，动态DOM插入后须立即调用翻译函数，语言包应扁平结构、统一路径、fetch加载并设fallback顺序，切换语言时须同步更新各元素lang属性、滚动位置及Intl实例，且不能仅依赖navigator.language。
直接用 data-i18n 标记 + 外部 JSON 语言包 + 同步更新 document.documentElement.lang，是当前最轻量、可调试、不依赖框架的可行路径。硬编码文案、只改根节点 lang、或靠 CSS 类显隐双语 DOM，都会在 SEO、可访问性、动态内容和 fallback 场景中出问题。
怎么给 HTML 元素打 data-i18n 标记才不会漏关键属性
所有要翻译的文本节点（<h1>、<p>、<button>、<label>）必须显式加 data-i18n 属性，值为英文小写+下划线键名，比如 "nav_home"。但仅设这个不够：
-
placeholder、title、alt这类属性不会被textContent覆盖，得额外加对应后缀：如data-i18n-placeholder="search_hint" -
value一般不翻译（表单输入值属于用户数据），跳过处理；但<label>的文字必须标记 - 含 HTML 结构的文案（如“请阅读 使用条款”）需用
innerHTML替换，且语言包里对应值必须是可信纯 HTML 片段，否则有 XSS 风险 - 动态插入的 DOM（弹窗、AJAX 表格行）插入后必须立即调用翻译函数，否则不会自动生效
- 别在
<script>、<style>、<pre>内部加data-i18n——这些节点不参与渲染，JS 替换无效
JSON 语言包怎么组织和加载才不容易翻车
每个语言一个独立文件，路径统一为 ./locales/${lang}.json，例如 ./locales/zh.json、./locales/en.json。结构必须扁平、键名严格一致：
- 所有文件字段完全对齐，某语言暂未翻译也要保留键，设为空字符串：
"btn_submit": ""，否则查不到 key 就留白 - 加载时用
fetch()，别硬编码对象到 JS 里；加try/catch包裹fetch和response.json() - fallback 顺序必须是：先试完整码（如
zh-HK），再截主语言（zh），最后退到默认语言（如en） - 服务器返回 JSON 时，HTTP
Content-Type必须是application/json，否则fetch可能静默失败
切换语言时为什么页面会闪动或读错语音
只替换文本、只改 document.documentElement.lang，屏幕阅读器仍按旧语言朗读，字体回退和标点间距也会错——因为浏览器和辅助技术按**每个元素自身的 lang 属性**决定行为，不是继承来的。
立即学习“前端免费学习笔记（深入）”；
- 切换前必须遍历所有已带
lang属性的元素（如<p lang="en">、<pre lang="bash">），把它们的lang值也同步更新（除非明确要保留原语言） - 更新 DOM 前，用
getComputedStyle记录滚动位置；更新完再window.scrollTo()恢复，否则页面会跳回顶部 - 若用了
moment.js，记得调用moment.locale('en')；若用原生Intl，需重建所有格式化实例，不能复用旧对象 - 动态字段（时间、数字、货币）必须重新用
Intl.DateTimeFormat或Intl.NumberFormat格式化，否则仍显示旧语言格式
为什么不能直接用 navigator.language 当作最终语言标识
navigator.language 返回的是浏览器 UI 语言（如 zh-CN），但用户实际偏好可能是 zh-HK 或仅 zh。更严重的是，某些安卓 WebView 返回空字符串或错误值，导致 fallback 失效。
- 优先读取 URL 参数（如
?lang=ja）→ 再查localStorage.getItem('preferred-lang')→ 最后 fallback 到navigator.language || 'en' - 服务端应通过
Accept-Language请求头解析首选语言，并注入为document.documentElement.lang，前端初始化时优先读取它，这样 CSR 和 SSR 渲染结果一致，SEO 友好 - 不要依赖
localStorage存语言偏好来覆盖服务端判断——它可能过期，且新设备首次访问没值 - 用户手动切换语言后，应发请求通知服务端（如
/api/locale），用于后续接口返回对应语言的错误消息等
最容易被忽略的是：动态插入的 DOM 节点、带 lang 属性的子元素、以及 Intl 格式化实例这三类，它们不会随根节点语言变更而自动更新，必须显式处理。
