HTML国际化怎么同步？多版本工程化维护技巧-html教程-PHP中文网

lang属性需逐节点更新，不能仅改根节点；data-i18n必须显式标记每个可翻译节点；语言包须扁平结构、键名对齐、utf-8无bom；切换语言应局部刷新，动态dom需手动翻译。

html国际化怎么同步？多版本工程化维护技巧

lang 属性必须逐节点更新，不能只改 document.documentElement.lang

浏览器和屏幕阅读器不继承 lang，每个节点的语音引擎、字体 fallback、标点间距、断行规则都取决于它自己的 lang 值。只设 document.documentElement.lang = 'zh-CN'，对已渲染的 <p lang="ja"></p> 或 <code lang="en"> 完全无效。

切换语言时必须同步遍历所有带 lang 属性的元素，按语义保留或重置：

主语言变更：更新根节点 + 所有未显式声明 lang 的文本容器（如 <div>、<code><p></p>）
局部多语言内容（引用、代码块、术语）要保留原 lang，比如 <blockquote lang="fr"></blockquote> 不能被批量替换成 zh-CN
lang 值必须符合 BCP 47 标准：用 zh-CN，不用 zh_CN 或 chinese；ja-JP 比 ja 更兼容 iOS VoiceOver

data-i18n 标记必须显式打在每个可翻译节点上

JS 不会自动识别 class、id 或 DOM 结构来决定哪段文本该换——它只认 data-i18n 属性。漏标一个 <button></button> 或 <input placeholder>，切换语言后就留白。

常见遗漏点：

Html2md

使用 Readability + Turndown 将 HTML 页面转换为干净的、Agent 友好的 Markdown。去除导航栏、广告、页脚、Cookie 横幅、社交按钮等干扰元素。支持 URL...

下载

<input data-i18n-placeholder="search_hint"> —— placeholder 需带后缀，data-i18n 默认只更新 textContent
<select></select> 的 <option></option> 必须单独加 data-i18n，父 <select></select> 上标没用
<svg><text data-i18n="chart.title"></text></svg> —— SVG 内文本节点也要标
含 HTML 结构的文案（如「服务条款即表示同意」）要用 innerHTML 替换，但语言包里对应值必须是可信的纯 HTML 片段，否则触发 XSS

语言包 JSON 文件必须结构扁平、键名严格对齐

别把语言包写成嵌套对象：{"ui": {"header": {"title": "..."}}}。这种结构会导致 key 路径不可预测，容易因某语言缺失某层而查不到值，最终渲染为空。

正确做法是每个语言一个文件，且键名完全一致：

locales/en.json：{"nav.home": "Home", "form.submit": "Submit", "error.required": "Required"}
locales/zh.json：{"nav.home": "首页", "form.submit": "提交", "error.required": "必填项"}
某语言暂未翻译，也得留空字符串："nav.home": ""，而不是直接删掉这个 key
所有文件必须 UTF-8 编码（无 BOM），否则 fetch() 读取时可能解析失败或乱码