HTML脚本怎么国际化？逻辑分离工程化规范-html教程-PHP中文网

data-i18n 标记需覆盖所有可翻译属性，必须显式声明 data-i18n-placeholder、data-i18n-alt 等后缀；语言包须扁平结构、键名对齐、bcp 47 命名；切换语言时须同步更新 document.documentelement.lang 及所有子元素 lang 属性，并重建 intl 实例、恢复滚动位置。

html脚本怎么国际化？逻辑分离工程化规范

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

只给 <h1 data-i18n="home.title"></h1> 加属性，切换后 <input placeholder="Search"> 还是英文——这是最常见翻车点。浏览器不会自动把 data-i18n 映射到 placeholder 或 alt 上。

必须显式声明对应后缀：

data-i18n-placeholder 用于 input、textarea
data-i18n-title 用于 tooltip 类提示
data-i18n-alt 用于 <img> 替代文本
data-i18n-aria-label 用于无障碍标签
value 属性一般跳过（属于用户输入数据），但 <button></button> 和 <input type="submit"> 的显示文案建议用 textContent 更新

含 HTML 结构的文案（如“请阅读服务条款”）需用 innerHTML 替换，但语言包里对应值必须是可信纯 HTML 片段，不能拼接用户输入，否则有 XSS 风险。

JSON 语言包结构必须扁平 + 键名对齐 + BCP 47 命名

语言包不是随便写个对象就行。zh.json 里有 "form.submit"，en.json 里漏了这键，JS 查不到就留空；某语言暂时没译完，也得保留键并设为空字符串："form.submit": ""，否则整个字段消失。

路径和命名要严格统一：

文件路径固定为 ./locales/zh-Hans.json、./locales/en-US.json（注意是连字符，不是下划线）
键名全小写+英文点号分隔，如 nav.home、error.network_timeout，禁用中文或空格
避免嵌套：不要 {"common": {"submit": "提交"}}，而用 {"common.submit": "提交"}
HTTP 返回时 Content-Type 必须是 application/json，否则 fetch() 可能静默失败

切换语言时必须同步更新 document.documentElement.lang 和所有子元素 lang 属性

只改 document.documentElement.lang = 'zh-Hans'，页面文字不会变，屏幕阅读器仍读英文，标点间距错乱，中文字体回退失效——因为浏览器和辅助技术按**每个元素自身的 lang 属性**决定行为，不继承。

Article To Html

文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。

下载

正确做法是遍历并同步更新：

所有带 lang 的语义化标签（<p></p>、<section></section>、<footer></footer> 等）都需设为当前语言码，如 lang="zh-Hans"
已有明确多语言内容的元素（如 <pre class="brush:php;toolbar:false;" lang="bash"></pre>、<code lang="sql">）保留原 lang 值，不参与更新
<script></script> 和 <style></style> 内部不加 lang，它们不参与文本渲染
动态插入的 DOM（弹窗、AJAX 表格行）插入后必须立即调用翻译函数，MutationObserver 不可靠，无法触发翻译

动态内容、表单状态、滚动位置必须保留在切换过程中

用 window.location.reload() 切语言？表单输入清空、路由重置、滚动跳顶——用户立刻想关网页。真正可用的切换是局部刷新。

关键动作要一次做完：

切换前用 getComputedStyle(document.scrollingElement).scrollTop 记录滚动位置
更新所有 data-i18n* 绑定的属性 + 同步 lang 属性
调用 Intl.DateTimeFormat 和 Intl.NumberFormat 重建实例（旧实例不会自动响应语言变更）
恢复滚动：window.scrollTo(0, savedScrollTop)
select 的 option 文字需单独处理：遍历 select[data-i18n] option，查语言包中 "xxx.options" 数组逐个赋值