语言切换入口必须是语义化或带role="button"的，需同步更新document.documentElement.lang及所有继承主语言的lang属性，并处理data-i18n属性、插值、表单placeholder等，优先依据Accept-Language而非localStorage。
语言切换入口必须是语义化
纯用 display: none 切换多套文案块（比如 <div data-lang="zh"> 和 <code><div data-lang="en">）会导致 SEO 抓取错乱、屏幕阅读器无法感知语言变更、且表单控件状态容易丢失。真正可用的入口只有两类：<code><select></select>（推荐，语义强、无障碍支持好）或带 role="button" 的 <button></button>（需手动处理键盘焦点和 aria-expanded）。
常见错误现象：Uncaught TypeError: Cannot read property 'value' of null——因为没给 <select></select> 加 id，JS 用 document.getElementById 拿不到；或者用了自定义下拉组件但没设 aria-label，导致读屏软件念不出“切换语言”。
-
<select id="lang-switcher"></select>必须有id，且每个<option></option>的value是标准 BCP 47 标签，如zh-Hans、en-US，别用chinese或zh_CN - 如果用按钮，得手动监听
Enter和Space键触发切换，不能只靠click - 入口元素本身也要加
data-i18n，比如<select data-i18n="lang.switcher.label"></select>，否则“Language”这个提示词没法翻译
点击后必须同步更新 document.documentElement.lang 和所有显式 lang 属性
只改文字不改 lang，等于没切——屏幕阅读器仍按旧语言朗读，中日韩混排时字体回退失效，标点间距异常，甚至拼写检查出错。而只改 document.documentElement.lang 又不够：页面里夹的英文术语、<pre class="brush:php;toolbar:false;" lang="bash"></pre>、引文段落等，都得各自保持原 lang 值，不能被全局覆盖。
- 切换时第一件事是执行
document.documentElement.lang = nextLang，值必须来自语言包映射，不是用户选的原始value（比如用户选zh，实际应设为zh-Hans） - 遍历所有带
lang属性的元素（document.querySelectorAll('[lang]')），跳过那些明确写死为非主语言的（如lang="en"的代码块），只更新继承主语言的局部容器（如<article lang="zh-Hans"></article>） - 别用
innerHTML重绘整个，那会清空表单、丢失滚动位置、触发重复初始化
data-i18n 属性要覆盖文本 + 属性 + 插值，不能只填 innerText
data-i18n 默认只替换元素的 textContent，但真实页面里大量文本藏在属性里：按钮的 title、输入框的 placeholder、图片的 alt、链接的 aria-label。漏掉这些，切换后鼠标悬停没提示、盲人用户听不到替代文字。
立即学习“前端免费学习笔记（深入）”；
- 用后缀扩展：写
data-i18n-title="tooltip.save"就自动设title，data-i18n-placeholder="search.hint"就设placeholder - 插值必须显式传参：语言包里写
"search.placeholder": "Search {type}"，JS 渲染时得调用类似format(key, { type: 'products' })，不能指望浏览器自动解析大括号 - 表单
<input>和<textarea></textarea>的value不建议用data-i18n更新——用户正在输入时会被清空；只处理placeholder和title
localStorage 存的是偏好，不是权威，不能覆盖 Accept-Language
用户第一次访问，优先级链条是：Accept-Language 请求头 > navigator.language（降级）> localStorage（仅作补充）> 默认语言（如 en）。强行用 localStorage 覆盖系统语言，会把日本用户用英文系统查资料时的 Accept-Language: en-US 硬切成日文，结果页面全乱。
- 保存时用
localStorage.setItem('preferred-lang', langCode)，但读取时必须先检查document.documentElement.lang（SSR 注入的）、再 fallback 到navigator.language - 安卓 WebView 或某些隐私模式下
navigator.language可能为空字符串，必须有兜底逻辑，否则整页文案留白 - 切换语言后，除了存
localStorage，还得发一次fetch加载对应 JSON 语言包（如/locales/zh-Hans.json），失败就 fallback 到en文件，不能静默失败
最易被忽略的点：语言包键名必须全项目统一，哪怕某语言还没翻译完，也要在 zh-Hans.json 里保留 "form.submit": "" 这样的空字段。否则 JS 查 dict['form.submit'] 返回 undefined，DOM 文本就变空白——这种问题上线后根本看不出日志，只能靠人工巡检。
