data-i18n属性需覆盖所有可翻译字段，包括title、aria-label、placeholder等；lang属性须显式设于各文本标签而非仅documentElement；语言包加载需fallback兜底；动态DOM插入后须手动触发翻译。
data-i18n 属性必须覆盖所有可翻译字段，不只是 textContent
只给 <button data-i18n="submit">提交</button> 加 data-i18n，切换后按钮文字变了，但鼠标悬停提示（title）、屏幕阅读器提示（aria-label）、输入框占位符（placeholder）全还是中文——这是最常被忽略的硬伤。
正确做法是显式标注每个需翻译的属性：
-
data-i18n→ 替换textContent或innerHTML（如<h2 data-i18n="home.title"></h2>） -
data-i18n-title→ 替换title属性（如<button data-i18n-title="tooltip.submit"></button>） -
data-i18n-placeholder→ 替换placeholder（如<input data-i18n-placeholder="search.hint">） -
data-i18n-aria-label→ 替换aria-label（尤其影响无障碍访问） -
value一般不翻译（属于用户输入数据），但<input type="submit">的显示文案建议用data-i18n控制textContent，而非改value
lang 属性不能只设在 documentElement 上
执行 document.documentElement.lang = 'zh-Hans' 看似“切语言”了，但屏幕阅读器仍按旧规则朗读，中英文标点间距错乱，字体回退也失效——因为浏览器和辅助技术查的是**每个元素自身的 lang 属性**，不是继承值。
必须为所有含文本的语义化标签显式设置 lang：
立即学习“前端免费学习笔记（深入）”；
- 静态内容：在
<h1></h1>、<p></p><div class="aritcle_card flexRow"> <div class="artcardd flexRow"> <a class="aritcle_card_img" href="/xiazai/skill12116" title="DeepBI DHTML 页面生成器"><img src="https://img.php.cn/upload/skill/001/246/273/6adaf20d3191a227.jpg" alt="DeepBI DHTML 页面生成器" ></a> <div class="aritcle_card_info flexColumn"> <a href="/xiazai/skill12116" title="DeepBI DHTML 页面生成器">DeepBI DHTML 页面生成器</a> <p>生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur</p> </div> <a href="/xiazai/skill12116" title="DeepBI DHTML 页面生成器" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div>、<section></section>、<footer></footer>等标签上加lang="zh-Hans" - 已有特殊
lang的元素（如<pre class="brush:php;toolbar:false;" lang="bash"></pre>、<code lang="sql">）保留原值，这是合法混排场景 -
<script></script>和<style></style>内部设lang没意义，不参与渲染 - 切换语言时，要遍历所有已带
lang的元素并批量更新，不能只改根节点
JSON 语言包加载和 fallback 必须有兜底逻辑
直接 fetch('./locales/zh.json') 而不处理失败，网络抖动或路径错误会导致整个页面文案空白；硬编码语言对象进 JS 又让维护成本飙升。
可靠做法：
- 语言包路径统一为
./locales/${lang}.json（如./locales/zh-Hans.json、./locales/en-US.json） - 加载时用
try/catch包裹fetch()和response.json() - fallback 顺序严格：先试完整 BCP 47 码（
zh-HK），再截主语言（zh），最后退到默认语言（如en） - 所有语言 JSON 字段必须对齐：某语言暂未翻译也要保留键，设为空字符串
"btn_submit": ""，否则查不到 key 就留白 - 服务器返回 JSON 时，
Content-Type必须是application/json，否则fetch可能静默失败
动态插入的 DOM 必须手动触发翻译
AJAX 加载的弹窗、分页表格新行、懒加载模块插入后，里面的 data-i18n 不会自动生效——DOM 更新不会触发翻译函数，这是最隐蔽的漏翻点。
应对方式：
- 弹窗打开后，立即调用翻译函数处理其内部节点（如
translateNode(modalEl)） - 表格每页请求返回新
<tr> 后，在插入前先执行翻译 <li>避免依赖 <code>MutationObserver全局监听（开销大、易误触），优先在插入点附近显式调用 - 含 HTML 结构的文案（如
"terms.link": "请阅读<a href="https://www.php.cn/link/07fd2295ead5c4d45892fe3ab22a846a">服务条款</a>"）要用innerHTML替换，且语言包值必须是可信纯 HTML 片段，否则有 XSS 风险
真正卡住人的从来不是“怎么写切换按钮”，而是 lang 属性没逐节点更新、data-i18n-placeholder 漏标、动态内容没补翻译——这些地方一漏，SEO、无障碍、用户实际体验就全垮了。
