HTML页面内容国际化和动态注入技术

作者：袖梨 2026-07-14

data-i18n标记必须覆盖所有可翻译属性，不只是textContent；placeholder、alt、title、aria-label等需显式加对应后缀，value属性一般不翻译，lang属性须全量同步，语言包字段须对齐，HTML注入须严格过滤防XSS。

data-i18n标记必须覆盖所有可翻译属性，不只是textContent

只给 <h1 data-i18n="home.title"> 加属性，但漏掉 <input placeholder="Search">，切换语言后 placeholder 还是英文——这不是漏翻译，是标记没打全。

常见错误现象：alt、title、aria-label、placeholder 这些属性不会被 textContent 更新逻辑触达，必须显式加后缀：

data-i18n-placeholder="search_hint"
data-i18n-alt="user_avatar"
data-i18n-title="tooltip_info"
data-i18n-aria-label="close_button"

value 属性一般不翻译（属于用户输入数据），但 <button> 和 <input type="submit"> 的显示文案建议用 textContent 更新，避免意外提交英文值。

JSON语言包加载失败时页面留白，怎么兜底

fetch() 加载 ./locales/zh.json 失败，或 key 查不到（比如 "nav_home" 在 zh.json 里缺失），默认行为是留空——用户看到空白按钮或标题，不是“未翻译”，而是“挂了”。

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

必须在加载和查找环节都加 fallback：

fetch 外层用 try/catch，失败时降级到 en.json 或内置默认对象
查 key 时用 langPack[key] ?? langPack.fallback ?? "MISSING_KEY"，不能直接 langPack[key]
所有语言包字段必须对齐：某语言暂未翻译也要保留键，设为空字符串 "btn_submit": ""，否则查不到就 undefined
HTTP 响应头 Content-Type: application/json 必须正确，否则 response.json() 静默抛错

切换语言时页面闪动或语音读错，根源在lang属性没同步

只执行 document.documentElement.lang = "zh-Hans"，但页面里已有 <p lang="en"> 或 <pre lang="bash">，屏幕阅读器仍按旧 lang 朗读，中文顿号间距错、英文字体回退失效——这不是 JS 没跑完，是浏览器根本不认根节点继承。

切换时必须做两件事：

遍历所有带 lang 属性的元素（document.querySelectorAll("[lang]")），除明确要保留原语言的（如 <pre lang="bash">），其余全部设为当前语言码
确保所有新插入的动态 DOM（AJAX 弹窗、分页表格行）插入后立即调用翻译函数，否则 data-i18n 标记只是字符串，不会自动生效
BCP 47 格式必须严格：用 zh-Hans，不用 zh_CN 或 chinese，后者会被忽略甚至触发 fallback 失败

外部文本注入与国际化混用时 XSS 风险高发点

用 <script src="output.txt"> 加载含变量声明的文本文件，再把内容塞进 <p>，如果这个文本来自 CMS 或日志生成，且语言包里又用了 innerHTML 渲染带链接的文案（如 "terms_link": "请阅读<a href="https://www.php.cn/link/07fd2295ead5c4d45892fe3ab22a846a">服务条款</a>"），XSS 就藏在中间。

安全边界必须划清：

纯文本内容一律用 textContent 注入，杜绝 HTML 解析
含结构的文案（如带 <strong> 或链接）必须走 innerHTML，但语言包对应值要是可信纯 HTML 片段——不能拼接用户输入，也不能执行 JS
动态注入的 HTML 片段（如弹窗内容）必须过 DOMPurify.sanitize()，哪怕来源是内部系统
<script> 和 <style> 内部禁止写 data-i18n——它们不参与渲染，JS 替换无效，还可能被误解析