必须用扁平JSON语言包+data-i18n显式标记，否则会导致漏翻、错位、不可调试；硬编码翻译键或写在HTML注释中会使新语言加字段需改多处、无法被工具扫描、翻译人员无法直接编辑；data-i18n须覆盖textContent及placeholder、alt、title等属性，动态插入内容需手动调用translateElement并同步设置lang属性。
必须用扁平 JSON 语言包 + data-i18n 显式标记，否则词条会漏翻、错位、不可调试。
为什么不能把翻译键写在 JS 对象里或 HTML 注释中
硬编码在 JS 里（如 { home_title: 'Home' }）会导致：新语言加字段要改多处、无法被 i18n 工具扫描、团队协作时翻译人员没法直接编辑 JSON；写在 HTML 注释里则完全不参与 DOM 遍历，querySelectorAll('[data-i18n]') 根本查不到。实际项目中，漏掉一个 data-i18n 就意味着某个按钮或 placeholder 永远是英文——而且上线后极难定位。
实操建议：
- 所有语言包统一存为
./locales/zh.json、./locales/en.json等，路径和命名严格固定 - 每个 JSON 文件结构必须扁平：
{"header_welcome": "Welcome", "form_email_placeholder": "Enter your email"}，禁止嵌套对象 - 未翻译字段也必须保留键，值设为空字符串
"btn_submit": ""，避免运行时 fallback 到 key 名本身
data-i18n 要覆盖哪些属性，不能只盯 textContent
只给 <button>Submit</button> 加 data-i18n="btn_submit"，但漏掉 data-i18n-title 或 data-i18n-placeholder，就会出现「按钮文字翻了，但 tooltip 还是英文」这类问题。浏览器不会自动把 translation 应用到属性上，必须显式声明。
立即学习“前端免费学习笔记（深入）”；
常见错误现象：
-
<input placeholder="Search">切换语言后 placeholder 不变 -
<img alt="user avatar">的alt文本没更新，影响无障碍访问 -
<label for="email">Email</label>翻译了，但for属性没同步，点击 label 失效
实操建议：
- 每个含文本的语义标签至少有一个基础
data-i18n键 - 需要翻译的属性，额外加对应后缀：
data-i18n-placeholder、data-i18n-alt、data-i18n-title -
value属性跳过处理（属于用户输入数据），但placeholder必须处理 - 含 HTML 结构的文案（如
"Please read <u>Terms</u>"）要用innerHTML替换，且语言包值必须是可信纯 HTML 片段，否则有 XSS 风险
动态插入内容的词条怎么保证不丢
AJAX 加载的弹窗、分页表格新行、懒加载模块，插入 DOM 后不会自动触发翻译——data-i18n 只是静态标记，不是响应式绑定。你看到的“刚打开 modal 里还是英文”，本质是忘了在 appendChild() 或 insertAdjacentHTML() 之后立刻调用翻译函数。
实操建议：
- 封装一个
translateElement(el)函数，接收单个节点，遍历其内部所有[data-i18n]并填充 - 所有动态插入逻辑末尾必须紧跟调用：
translateElement(modalEl)或translateElement(tableRow) - 不要依赖 MutationObserver 全局监听——性能差、易漏事件、对 SSR 不友好
- 第三方组件（如日期选择器）需单独调用其国际化 API，不能指望
data-i18n自动生效
lang 属性不逐层设置，字体和语音就全乱套
只执行 document.documentElement.lang = 'zh' 是无效的。屏幕阅读器按每个元素自身的 lang 属性朗读，标点间距、连字规则、字体回退链也全靠它决定。你看到的「顿号太宽」「<pre lang="bash"> 代码被中文字体覆盖」「<title> 没变语言」，都是因为只有根节点有 lang，子元素全是继承来的空值。
实操建议：
- 所有含文本的语义化标签（
<h1>、<p>、<section>、<footer>）都显式加lang属性，值与当前语言包一致 - 已有明确语言的特殊元素（如
<pre lang="bash">、<code lang="sql">）切换语言时保留原值，这是合法混排场景 -
<script>和<style>内部不要加lang，它们不参与文本渲染 - 切换语言时，必须遍历所有已带
lang属性的元素并同步更新，不能只改根节点
最常被忽略的是：动态插入的节点（比如 AJAX 返回的 <div><p data-i18n="msg"></p></div>）不仅得调 translateElement()，还得手动补上 lang="zh" ——否则即使文字翻了，语音和排版仍按旧语言走。
