lang属性必须显式写在每个含文本的语义化标签上，因浏览器和屏幕阅读器按各元素自身lang值决定标点、连字、字体回退与语音朗读，不继承父级；代码块、title、meta等需单独设置；data-i18n不作用于placeholder等属性，须用后缀显式声明；动态dom需手动触发翻译；语言包应模块化并兼顾ssr/csr一致性；lang值错误比不写更糟。

lang 属性必须显式写在每个含文本的语义化标签上

只改 document.documentElement.lang，页面文字不会变、屏幕阅读器仍读错、标点间距乱、字体回退失效——这不是国际化，只是改了个标签。

浏览器和屏幕阅读器按**每个元素自身的 lang 属性**决定标点宽度、连字规则、字体回退链、语音朗读方式，不继承父级。所以 <h1></h1>、<p></p>、<section></section>、<footer></footer> 等所有含文本的语义化标签，都得手动加 lang="zh-Hans" 或 lang="en"。

• <pre class="brush:php;toolbar:false;" lang="bash"></pre>、<code lang="sql"> 这类已有 lang 的代码块，切换语言时要保留原值，这是多语言混排的合法场景
• <title></title>、<meta name="description"> 完全不继承 的 lang，必须单独设
• <script></script> 和 <style></style> 内部设 lang 没意义，它们不参与文本渲染

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

data-i18n 只作用于元素的 textContent，对 placeholder、title、alt、aria-label 等属性完全无效。

常见错误现象：<input placeholder="Search"> 切换语言后还是英文；<img alt="user avatar"> 的替代文本没更新；<label for="email">Email</label> 文字翻了但 for 没同步，点击 label 失效。

html-deploy

使用 htmlcode.fun 将 HTML 内容或文件部署到网页，适用于用户要求“部署到网页”“托管此 HTML”“生成此前端...的实时链接”等场景。

下载

• 必须显式加对应后缀：如 data-i18n-placeholder="search_hint"、data-i18n-alt="avatar_desc"、data-i18n-title="tooltip_info"
• value 属性一般不翻译（属于用户输入数据），跳过处理；但 <button></button> 和 <input type="submit"> 的显示文案建议统一用 textContent 更新，避免 value 被意外提交
• 含 HTML 结构的文案（如“请阅读服务条款”）必须用 innerHTML 替换，且语言包里对应值要是可信纯 HTML 片段（不能带用户输入、不执行 JS），否则有 XSS 风险

动态插入的 DOM 必须手动触发翻译

AJAX 加载的弹窗、表格行、懒加载模块插入后，如果没调用翻译函数，里面的 data-i18n 标记就只是字符串，不会变成对应语言文本。

例如：<modal></modal> 里的 <h2 data-i18n="modal_title"></h2> 不会自动更新；分页表格每页 AJAX 获取新 <tr>，新行里的 <code>data-i18n 保持原始键名，需插入后立即遍历并替换。

• 不要依赖 MutationObserver 自动监听——开销大、易漏、难调试；明确在 DOM 插入后调用一次翻译函数更可控
• 第三方组件（如日期选择器）内部文本通常不响应 data-i18n，需查其文档看是否支持 locale 配置或提供 API 手动刷新
• 若使用 Intl.DateTimeFormat 或 Intl.NumberFormat，语言切换后必须重建实例，旧对象不会自动更新格式

语言包结构与切换逻辑必须兼顾 SSR 和 CSR 一致性

浏览器 navigator.language 不可靠（用户可能改过设置，或使用隐私模式），而纯前端检测又无法支持 SSR 场景。最稳的方式是：由服务端通过 Accept-Language 请求头解析出首选语言，并注入为全局 JS 变量或 的 lang 属性。

前端初始化时优先读取 document.documentElement.lang，fallback 到 navigator.language，再 fallback 到默认语言（如 en）。这样 CSR 和 SSR 渲染结果一致，SEO 友好，也避免首次渲染语言错乱。

• JSON 语言包建议按功能模块拆分（如 common.json、form.json），用 Promise.all 并行加载，减少首屏等待
• 不要依赖 localStorage 存语言偏好来覆盖服务端判断——它可能过期，且新设备首次访问没值
• 如果用户手动切换语言，应同时发请求通知服务端（如 /api/locale），用于后续接口返回对应语言的错误消息等

真正容易被忽略的是：lang 值错误比不写更糟。一个拼错的 lang="zh-CN"（正确应为 zh-Hans 或 zh-Hant）会导致字体回退链断裂、标点渲染异常、屏幕阅读器朗读失准——这些问题往往在测试阶段难以复现，上线后才陆续暴露。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！