改document.documentElement.lang无效，因浏览器和屏幕阅读器按各元素自身lang属性判断语言行为，不继承父级；必须逐个更新语义化标签的lang属性并同步调用翻译函数。

为什么改了 document.documentElement.lang 文本还是不换

因为 document.documentElement.lang 只影响根节点的语言声明，浏览器和屏幕阅读器不会据此重绘或重读已有子元素。你看到的“没换”其实是 DOM 已渲染完毕、JS 仅改了 lang 属性但没动文本内容。

常见错误现象：

首页

切换语言后仍显示“首页”，控制台也没报错——说明 data-i18n 没被扫描到，或语言包加载失败，或键名对不上。

• 先检查是否调用了翻译函数（如 translateAll()），不是设完 lang 就自动生效
• 用浏览器 Elements 面板搜索 data-i18n，确认目标元素确实带这个属性（别漏写、别拼错、别藏在 <script></script> 或
  里）
• 打开 Network 面板，看 ./locales/zh.json 这类请求是否 200，响应体是不是合法 JSON（注意 BOM 和 UTF-8 编码问题）
• 在控制台执行 console.log(i18nData?.['home.title'])，确认语言包里真有这个 key，且值非空字符串

data-i18n 生效了但 placeholder/alt 还是英文

data-i18n 默认只更新元素的 textContent，对属性完全无效。这是最常被忽略的漏点，不是 bug，是设计如此。

实操建议：

• 必须显式加带后缀的标记：
• 同理处理：data-i18n-alt、data-i18n-title、data-i18n-aria-label
• 别碰 value 属性——表单输入值属于用户数据，不应翻译；但 显示文案建议统一走 textContent 更新
• 含 HTML 的文案（如“请阅读服务条款”）要用 innerHTML 替换，且语言包里对应值必须是可信纯 HTML 片段（不能拼接用户输入）

切换后屏幕阅读器仍读错、顿号间距乱、中文字体没生效

这些都不是文本没换，而是 lang 属性没同步更新到具体语义元素上。浏览器按每个元素自己的 lang 决定语音、标点、字体回退，不继承父级。

调试步骤：

DeepBI DHTML 页面生成器

生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur

下载

• 用 Elements 面板选中一段中文文字，右键 → “Edit as HTML”，看它是否有 lang="zh-Hans"；没有？就是漏设
• 执行 document.querySelectorAll('[lang]')，检查返回列表是否覆盖所有含文本的语义标签（
  、
  、
  等）
• 切换语言时，必须遍历这些元素并重设：el.lang = 'zh-Hans'；特别注意保留已有的多语言混排，比如
  不要被覆盖
• 验证 BCP 47 格式：用 zh-Hans，别用 zh_CN、chinese——写错会导致 CSS :lang(zh-Hans) 伪类不匹配、i18n 库 fallback 失败

动态插入的 DOM（弹窗、AJAX 表格行）怎么补翻译

全局扫描函数（如 translateAll()）只在初始化或手动触发时运行，不会监听新节点。插入后不处理，就永远是默认语言。

正确做法：

• 在 appendChild() 或 insertAdjacentHTML() 后立即调用翻译函数，例如：translateElement(newRow, 'table.row')
• 避免深度嵌套：DOM 路径从 到 data-i18n 元素超过 6 层时，部分遍历逻辑可能跳过（尤其老浏览器或性能敏感场景）
• 用语义化标签替代纯
  堆叠：

  、

  天然中断嵌套层级，也便于工具识别作用域
• IE11 不支持 element.dataset.i18n，需兜底用 element.getAttribute('data-i18n')

真正卡住人的往往不是“怎么切”，而是“切完谁来管状态”：表单输入值、滚动位置、第三方组件（如日期选择器）的语言实例、甚至 MutationObserver 是否监听到新节点——这些细节不串起来，调试就会陷入“文本换了但体验崩了”的怪圈。