HTML国际化怎么落地？大型项目工程化实践-html教程-PHP中文网

必须逐元素显式设置lang属性并同步更新所有data-i18n对应属性，仅改document.documentElement.lang无效；需遍历所有含lang元素和data-i18n节点，手动触发翻译，动态DOM插入后立即处理，语言包加载须校验MIME与状态并设fallback。

html国际化怎么落地？大型项目工程化实践

lang 属性必须逐层显式设置，不能只改 documentElement

只执行 document.documentElement.lang = 'zh-HK'，页面上 90% 的文本仍按旧语言渲染——标点间距错乱、字体回退失效、屏幕阅读器读错语音。浏览器和辅助技术不继承 lang，而是逐个检查每个元素自身的 lang 属性。

实操建议：

Wechat Article Html

将 Markdown 文章转换为微信公众号兼容的纯 HTML 格式。当用户要求"转成微信格式"、"生成公众号文章 HTML"、"排版到微信草稿箱"、"微信粘贴格式"时触发。输出带内联样式的纯 HTML，微信编辑器可直接渲染，无需额外适配。支持标题、段落、列表、粗体、行内代码、表格、引用块、代码块、配图的完整转换。

下载

所有含文本的语义化标签（、、、）都必须显式写 lang，值与当前激活语言包一致
已有明确语言用途的元素（如、）切换主语言时保留原 lang，不覆盖
<script></script> 和内部加 lang 无效，直接删掉
切换语言时，需遍历 document.querySelectorAll('[lang]') 并逐个赋值，不能只动根节点

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

只给加 data-i18n="btn_submit"，但漏掉 placeholder 或 aria-label，会导致表单提示、无障碍播报始终是英文，且无任何报错提示。

实操建议：

每个要翻译的元素至少有一个基础 data-i18n 键；若含 placeholder，额外加 data-i18n-placeholder；同理 data-i18n-title、data-i18n-alt
value 属性一般不翻译（属于用户输入数据），但和的显示文案需处理（它们可能用 textContent 或 value 渲染）
的需单独遍历，不能靠父级 data-i18n 推导
含 HTML 结构的文案（如“请阅读服务条款”）必须用 innerHTML 替换，但语言包里对应值必须是可信纯 HTML 片段，否则有 XSS 风险

动态插入的 DOM 必须手动触发翻译，不会自动监听

AJAX 加载的弹窗、分页表格新行、懒加载模块插入后，里面的 data-i18n 标记只是字符串——没调用翻译函数，就不会变成目标语言文本，控制台也无报错。

实操建议：

在 appendChild() 或 insertAdjacentHTML() 后立即调用翻译函数（如 i18n.translate(el)），不能依赖全局扫描
内的节点需单独识别，普通遍历会跳过
SSR 首屏 HTML 中，若 data-i18n 出现在 DOM 深度 >6 层（如嵌套 7 个），多数轻量翻译脚本会截断遍历，导致漏翻译——应改用、等语义标签中断深度语言包加载必须带校验和 fallback，不能硬编码或裸 fetch 把语言包直接写进 JS，或只用 fetch('./locales/en-US.json') 不检查响应状态，会导致构建体积膨胀、404 静默失败、MIME 类型错误（如返回 text/plain）时解析崩溃。实操建议：路径统一为 ./locales/${lang}.json，例如 ./locales/zh-Hans.json、./locales/en-US.json 加载必须用 fetch() + try/catch，内部检查 response.ok 和 response.headers.get('content-type')?.includes('application/json') fallback 顺序：先试完整 BCP 47 码（zh-HK），再截主语言（zh），最后兜底到内置默认对象（非空字符串占位）不要依赖 localStorage 决定首次加载语言——用户可能清过缓存；优先用 document.documentElement.lang（SSR 注入）或 navigator.language DOM 深度、lang 同步粒度、动态节点触发时机、语言包 MIME 校验——这四点最容易被忽略，但任一缺失都会导致上线后部分文字“卡在旧语言”，且难以复现和定位。