最可靠路径是data-i18n标记+BCP 47 JSON包+fetch加载+同步更新lang和localStorage；需为所有可见文本节点显式加data-i18n，属性类用data-i18n-placeholder等后缀，键名统一扁平，文件按BCP 47命名并降级加载，切换时必须同步更新document.documentElement.lang、局部lang属性及localStorage。
纯前端实现 HTML 多语言切换，最可靠、易维护的路径是：用 data-i18n 标记文本节点 + 按 BCP 47 规范组织 JSON 语言包 + fetch() 动态加载 + 同步更新 document.documentElement.lang 和 localStorage。不推荐硬编码文案、双语 DOM 显隐或仅改 lang 属性。
怎么给 HTML 元素打翻译标记才不会漏翻
所有要动态换语言的可见文本节点（<h1>、<p>、<button>、<input> 等）必须显式加 data-i18n 属性，值为统一键名，比如 "header_title"；placeholder、title、alt 这类属性不能靠 textContent 覆盖，得额外加 data-i18n-placeholder、data-i18n-title 等对应后缀；不要用 id 或 class 当键名——语义冲突、后期改文案时极易漏掉；动态插入的 DOM（如弹窗、表格行）插入后必须立即调用翻译函数，否则不会生效。
JSON 语言包怎么组织才不崩
每个语言一个文件，路径固定，例如 locales/zh-Hans.json、locales/en.json、locales/ja.json；结构必须扁平、纯键值对，不能嵌套：{"header_title": "欢迎", "btn_submit": "提交"}；所有文件键名严格一致，哪怕某语言暂未翻译，也要留空字符串或占位符，否则查不到 key 就显示原始键名；文件名必须符合 BCP 47 标准（如 zh-Hans，不是 zh_CN 或 chinese）；fetch() 加载时必须加 try/catch，网络失败或 JSON 解析出错不能让整个翻译流程中断；用户选了 zh-HK 但只有 zh-Hans.json，必须降级加载主语言包（如 en.json），否则页面文案会全空。
切换语言时必须同步更新哪些东西
只替换文本是无效的：屏幕阅读器仍按旧语言朗读，中日韩字体回退链失效，拼写检查错乱；必须同步执行以下操作：document.documentElement.lang = 'zh-Hans'（影响 SEO、字体、语音合成）；遍历所有已渲染的 lang 属性节点，手动更新非根节点的 lang 值（比如页面里有 <p lang="en">API</p>，它不能继承根节点语言，得自己保持原样）；localStorage.setItem('lang', 'zh-Hans') 必须在语言包成功加载并完成文本替换后才执行，否则刷新页面可能拿到未就绪的语言状态；别用 window.location.reload()，会导致白屏和状态丢失。
立即学习“前端免费学习笔记（深入）”；
最容易被忽略的是局部 lang 属性的维护——混排内容（英文术语、代码块、引文）一旦没显式保留原 lang，切到其他语言后会被错误地当成目标语言渲染，轻则标点间距异常，重则语音朗读完全错乱。
