data-i18n属性需覆盖所有可翻译字段，包括title、aria-label、placeholder等；lang属性须显式设于各文本标签而非仅documentElement；语言包加载需fallback兜底；动态DOM插入后须手动触发翻译。
data-i18n 属性必须覆盖所有可翻译字段，不只是 textContent
只给 加 data-i18n，切换后按钮文字变了，但鼠标悬停提示（title）、屏幕阅读器提示（aria-label）、输入框占位符（placeholder）全还是中文——这是最常被忽略的硬伤。
正确做法是显式标注每个需翻译的属性：
-
data-i18n→ 替换textContent或innerHTML（如） -
data-i18n-title→ 替换title属性（如） -
data-i18n-placeholder→ 替换placeholder（如） -
data-i18n-aria-label→ 替换aria-label（尤其影响无障碍访问） -
value一般不翻译（属于用户输入数据），但的显示文案建议用data-i18n控制textContent，而非改value
lang 属性不能只设在 documentElement 上
执行 document.documentElement.lang = 'zh-Hans' 看似“切语言”了，但屏幕阅读器仍按旧规则朗读，中英文标点间距错乱，字体回退也失效——因为浏览器和辅助技术查的是**每个元素自身的 lang 属性**，不是继承值。
必须为所有含文本的语义化标签显式设置 lang：
- 静态内容：在
、、、等标签上加lang="zh-Hans" - 已有特殊
lang的元素（如、）保留原值，这是合法混排场景 -
<script></script>和内部设lang没意义，不参与渲染 - 切换语言时，要遍历所有已带
lang的元素并批量更新，不能只改根节点
JSON 语言包加载和 fallback 必须有兜底逻辑
直接 fetch('./locales/zh.json') 而不处理失败，网络抖动或路径错误会导致整个页面文案空白；硬编码语言对象进 JS 又让维护成本飙升。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
可靠做法：
- 语言包路径统一为
./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)） - 表格每页请求返回新
后，在插入前先执行翻译 - 避免依赖
MutationObserver全局监听（开销大、易误触），优先在插入点附近显式调用- 含 HTML 结构的文案（如
"terms.link": "请阅读@#@#@#@#@#@#@#@#@#@0"）要用innerHTML替换，且语言包值必须是可信纯 HTML 片段，否则有 XSS 风险真正卡住人的从来不是“怎么写切换按钮”，而是
lang属性没逐节点更新、data-i18n-placeholder漏标、动态内容没补翻译——这些地方一漏，SEO、无障碍、用户实际体验就全垮了。 - 避免依赖
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
