基于HTML文档流的国际化布局维护技巧-html教程-PHP中文网

lang属性必须逐元素设置，data-i18n需覆盖所有可翻译属性，动态插入dom后须手动触发翻译，三者缺一不可。

基于html文档流的国际化布局维护技巧

lang 属性必须逐元素设置，不能只改 `document.documentElement.lang`

只执行 document.documentElement.lang = 'zh-Hans'，页面文字不会自动变、屏幕阅读器仍读英文、中文顿号间距错乱、<pre class="brush:php;toolbar:false;" lang="bash"></pre> 里的代码字体被中文字体覆盖——浏览器和辅助技术根本不看根节点 lang，而是逐个检查每个含文本元素自身的 lang 属性。

实操建议：

html-to-pptx

将多页 HTML 演示文稿转换为美化的 PPTX 文件，便于分享和分发。

下载

所有含文本的语义化标签（<h1></h1>、<p></p>、<section></section>、<footer></footer>、<label></label>）都得显式写 lang，值与当前语言包一致，比如 <p lang="zh-Hans">欢迎</p>
已有明确语言用途的元素（如 <pre class="brush:php;toolbar:false;" lang="bash"></pre>、<code lang="sql">）切换语言时保留原 lang 值，这是合法混排，不是 bug
<script></script> 和 <style></style> 内部写 lang 没意义，它们不参与文本渲染

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

只给 <button>提交</button> 加 data-i18n="btn_submit"，但漏掉 placeholder 或 aria-label，结果输入框提示仍是英文、屏幕阅读器播报错位——data-i18n 默认只替换文本内容，对属性完全无效。

实操建议：

每个要翻译的元素至少有一个基础 data-i18n 键；含 placeholder 就额外加 data-i18n-placeholder；同理 data-i18n-title、data-i18n-alt、data-i18n-aria-label
value 属性一般不翻译（属于用户输入数据），但 <button></button> 和 <input type="submit"> 的显示文案建议统一走 textContent 更新
含 HTML 结构的文案（如“请阅读服务条款”）必须用 innerHTML 替换，且语言包里对应值要是可信纯 HTML 片段，否则有 XSS 风险

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

AJAX 加载的弹窗、分页表格新行、懒加载模块插入后，里面的 data-i18n 标记只是字符串，不会变成对应语言文本——DOM 插入和事件监听是两件事，i18n 工具不会自动遍历新节点。

实操建议：

弹窗打开后，在 appendChild 或 insertAdjacentHTML 之后立即调用翻译函数，例如 translateElement(modalEl)
分页获取新 <tr> 后，对这批新节点做一次 <code>querySelectorAll('[data-i18n]') 并逐个替换
避免在 setTimeout 里延迟翻译——竞态下可能漏掉或重复执行

UTF-8 编码与 BOM 必须全局统一，否则 `<meta charset="UTF-8">` 会失效

<meta charset="UTF-8"> 写在开头也没用，如果 HTML 文件本身是 GBK 编码、或带 BOM 的 UTF-8、或编辑器保存时选了 “UTF-8 with BOM”，浏览器实际解析出的字符就是乱码——HTML 解析器只读前 1024 字节找 <meta charset>，BOM 或错误编码会让它直接 fallback 到系统默认（Windows 是 GBK）。

实操建议：

所有源文件（.html / .css / .js / .json）统一保存为 UTF-8 无 BOM；VS Code 保存时选 “UTF-8”，别选 “UTF-8 with BOM”
用十六进制查看器确认文件开头：UTF-8 无 BOM 应是 3C 21 64 6F...（即 ），带 BOM 是 <code>EF BB BF 3C 21...
HTTP 响应头 Content-Type: text/html; charset=UTF-8 必须与 &lt/meta> 一致；Nginx 配置里写 charset utf-8;，Apache 用 AddDefaultCharset UTF-8

最易被忽略的是：lang 属性粒度、data-i18n 属性覆盖范围、动态节点翻译时机这三者必须同步更新，缺一不可。一个没设 lang 的 <p></p> 即使文本翻对了，标点和字体回退还是错的；一个漏掉 data-i18n-placeholder 的输入框，切换语言后提示永远卡在英文；一段没手动触发翻译的 AJAX 表格行，永远显示原始 key。