如何构建支持多语言的HTML国际化组件

data-i18n 属性必须显式添加到所有用户可见静态文本节点，值为语言包键名；JS 不自动推断内容，仅识别该属性；动态插入 DOM 需手动调用翻译函数，fetch 失败须 fallback，lang 属性需语义准确且及时同步。

data-i18n 属性怎么打才不漏文本

所有用户可见的静态文本节点，必须显式加 data-i18n，值为语言包里的键名，比如 "header_title" 或 "form_email_required"。JS 不会自动推断 class、id 或内容本身——它只认这个属性。

• <h1 data-i18n="welcome">欢迎</h1> ✅ 有效
• <input placeholder="邮箱地址" data-i18n-placeholder="form_email"> ✅ 替换 placeholder
• <button data-i18n="submit_btn">提交</button> ✅ 同时覆盖 textContent 和 value（推荐统一用 textContent）
• <select data-i18n="country_select"><option>中国</option></select> ❌ 错误：option 文字需单独标，如 <option data-i18n="country_china">中国</option>
• <script>console.log("error");</script> ❌ 不渲染为可见文本，加了 data-i18n 无意义

JSON 语言包结构和加载失败怎么兜住

语言包必须扁平、键名一致、路径可预测，否则查不到 key 就留白——用户看到的是空格或原始键名，不是“加载中”。

• 每个语言一个文件：locales/zh-CN.json、locales/en-US.json，内容全是顶层键值对：{"login_btn": "登录", "header_title": "欢迎"}
• 缺失翻译也要保留键："nav_help": "" 或 "nav_help": "[未翻译]"，避免 JS 查找返回 undefined
• fetch 失败必须 fallback：try/catch 包住 fetch('./locales/' + lang + '.json')，捕获 TypeError: Failed to fetch 或 404
• fallback 优先级建议：先试完整码（zh-HK），再截主语言（zh），最后退到内置默认对象（硬编码英文）
• 服务端返回 JSON 时，响应头必须含 Content-Type: application/json，否则 response.json() 可能静默失败

为什么 document.documentElement.lang 改了但屏幕阅读器还是读中文

因为浏览器和辅助技术按每个元素自己的 lang 属性决定语音引擎、字体 fallback 和标点行为——不是继承来的。根节点改了，已渲染的子节点完全不受影响。

• 页面初始化时，必须设 document.documentElement.lang = 'zh-CN'（注意：用 zh-CN，别用 zh_CN 或 chinese）
• 切换语言后，要遍历所有已有 lang 属性的元素（如 <p lang="ja">…</p>），判断是否需同步更新；明确要保留原语言的（如代码块、引文），则跳过
• 局部多语言内容必须显式写内联 lang：<code lang="bash">npm install</code>、<blockquote lang="fr">…</blockquote>
• CSS 中可用 html[lang="zh-CN"] 做字体或间距适配，但不能指望它触发翻译

动态插入的 DOM 怎么立刻翻译

静态 HTML 加载完一次替换即可，但 JS 动态生成的内容（弹窗、AJAX 表格行、Toast 提示）不会自动触发翻译，必须手动调用翻译函数。

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

• 封装一个 t(key, opts?) 函数，内部查当前激活语言包，支持插值（如 "hello {name}" → t('welcome', { name: 'Alice' })）
• 插入新节点后立即处理：el.appendChild(newNode); translateNode(newNode);
• SVG 内文本需特殊识别：if (node instanceof SVGTextElement) node.textContent = ...
• 避免用 innerHTML 替换整个容器——会丢事件监听器；优先用 textContent 更新纯文本，仅当语言包值确认可信时才用 innerHTML
• 表单控件（select 的 option、input 的 placeholder）必须在插入后逐个遍历设置，不能只靠父级 data-i18n

真正难的不是加标记或换文案，而是让每处 lang 属性都语义准确、每次动态插入都及时翻译、每个 fetch 失败都有降级路径——这些细节不处理，多语言就只是表面切换。