只改 document.documentElement.lang 不够用，因为浏览器和屏幕阅读器逐个检查各元素自身的 lang 属性；data-i18n 默认仅更新 textContent，placeholder、alt 等需显式标记如 data-i18n-placeholder；动态插入的 DOM 必须手动触发翻译；lang 属性须逐个同步，语义化标签均需显式设置，确保标点、语音、字体等语义正确。

为什么只改 document.documentElement.lang 不够用

因为浏览器和屏幕阅读器不看根节点 lang 做渲染决策——它们逐个检查每个元素自身的 lang 属性。只设 document.documentElement.lang = 'zh-Hans'，已存在的 <p lang="en">API</p> 仍按英文朗读、标点间距、字体 fallback 渲染；<pre lang="bash"> 里的代码可能被中文字体覆盖。这不是国际化，是贴了个标签。

data-i18n 只更新 textContent，其他属性必须显式标记

常见错误：给 <input placeholder="Search"> 加 data-i18n="search_hint"，结果 placeholder 没变。因为 data-i18n 默认只作用于 textContent，对 placeholder、alt、title、aria-label 等完全无效。

• 要更新 placeholder，必须写 data-i18n-placeholder="search_hint"
• 要更新 alt，必须写 data-i18n-alt="avatar_desc"
• 要更新 title 或 aria-label，对应加 data-i18n-title / data-i18n-aria-label
• value 一般不翻译（属于用户输入数据），但 <button> 和 <input type="submit"> 的显示文案建议统一走 textContent 更新，避免 value 被意外提交

动态插入的 DOM 必须手动触发翻译

AJAX 加载的弹窗、分页表格新行、懒加载模块插入后，里面的 data-i18n 不会自动生效。JS 不监听 DOM 插入事件做翻译，这是常见漏点。

Article To Html

文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。

下载

• 弹窗打开后，需立即遍历其内部所有带 data-i18n 的元素并调用翻译函数
• 表格每页返回新 <tr>，插入后要主动执行 translateElement(row) 或类似逻辑
• 不要依赖 MutationObserver 自动扫描——开销大、易漏、难调试；明确在插入后调用更可控

lang 属性必须逐个同步，不能靠继承

切换语言时，除了更新文案，还得遍历所有已有 lang 属性的元素，把它们的值也同步成当前主语言，除非该元素明确要保留原语言（如引用日文原文、代码块）。

立即学习“前端免费学习笔记（深入）”；

• <p lang="en">React</p> 在中文页里应改为 lang="zh-Hans"，否则顿号按英文间距渲染
• <pre lang="bash"> 和 <code lang="sql"> 是合法混排，保留原值，不改
• <blockquote lang="fr"> 这类局部多语言内容，切换主语言时不能跟着变，要跳过
• 所有含文本的语义化标签（<h1>、<p>、<section>、<footer>）都得显式设 lang，值与当前语言包一致

细粒度控制的关键不在“多”，而在“准”：每个可读文本节点、每个属性、每个动态片段、每个 lang 值，都得有明确归属和更新路径。漏掉任何一个，就可能让标点错位、语音读错、字体失效——这些都不是样式问题，是语义断裂。