设计师与前端须统一使用扁平小写+点号键名（如home.title、form.submit）标注文案，语言包结构必须完全对齐，配合vs code插件校验、keys.md文档说明及data-i18n后缀精准标记各属性，并显式设置每个文本节点的lang属性以保障多语言渲染准确性和无障碍访问。
怎么让设计师和前端用同一套语言键名协作
设计师出稿时必须按 home.title、form.submit 这类扁平小写+点号的键名标注文案，不能写“首页标题”或“提交按钮”这种自然语言。前端拿到后直接照抄进 JSON 语言包，避免中间翻译层引入歧义或漏项。
常见错误现象：设计师用 Sketch 插件导出文案为 Excel，键名带空格或中文，前端手动改造成 home_title，结果某处漏了下划线，查不到 key 就留白；或者键名嵌套成 ui.header.mainTitle，JS 解析时没做递归查找，直接 fallback 到空字符串。
- 所有语言包必须结构扁平，键名完全对齐，哪怕某语言暂未翻译也要保留字段并设为空字符串：
"nav.about": "" - 建议用 VS Code 插件（如 i18n-ally）实时校验键名一致性，打开 en.json 和 zh.json 时自动标红缺失字段
- 设计交付物里附一份
keys.md文档，列明每个键的使用场景（如search.placeholder仅用于 的 placeholder 属性），避免前端误用到textContent
data-i18n 属性怎么打才不漏关键节点
data-i18n 不是加在父容器上就万事大吉——它只作用于当前元素的 textContent，对 placeholder、title、alt、aria-label 完全无效。这些属性必须显式用带后缀的 data 属性标记。
常见错误现象：<input placeholder="Search"> 加了 data-i18n="search.placeholder"，但没加 data-i18n-placeholder，切换语言后 placeholder 还是英文；<img alt="user avatar"> 没标 data-i18n-alt，屏幕阅读器仍读英文。
-
<button data-i18n="btn_submit">Submit</button>→ 正确更新按钮文字 -
<input data-i18n-placeholder="search_hint" placeholder="Search">→ 更新 placeholder -
<img data-i18n-alt="avatar_desc" alt="user avatar">→ 更新 alt 文本 -
<label data-i18n="form.email">Email</label>→ 更新 label 文字，for属性不动（它是 DOM 关联标识，不是文案） - 别在
<script></script>、<pre class="brush:php;toolbar:false;"></pre>、<style></style>内部加data-i18n—— 这些节点不渲染为可见文本，加了无意义
切换语言时 DOM 怎么局部刷新不丢状态
暴力 window.location.reload() 或整页替换 innerHTML 会清空表单输入值、滚动位置、已初始化的第三方组件（比如日期选择器）。正确做法是只遍历带 data-i18n 的节点，逐个更新内容，并同步重建 Intl 格式化实例。
常见错误现象：切换语言后页面跳回顶部；用户刚输一半的邮箱被清空；<input type="date"> 的日历控件语言没变，仍显示英文月份；弹窗里的 data-i18n 标记没生效，因为弹窗是 AJAX 动态插入的。
- 更新前用
window.scrollY记录位置，更新后调用window.scrollTo(0, y)恢复 - 表单
value属性不翻译（属于用户数据），只处理placeholder、title等提示类属性 - 动态插入的 DOM（弹窗、分页表格行）插入后必须立即调用翻译函数，例如
translateDOM(modalElement) - 若用了
Intl.DateTimeFormat，切换语言后需新建实例：new Intl.DateTimeFormat(lang, options)，旧对象不会自动更新
lang 属性为什么必须每个元素单独设
只改 document.documentElement.lang 对已渲染的子元素完全无效。浏览器和屏幕阅读器按每个元素自身的 lang 属性决定语音引擎、字体 fallback、标点间距、断行规则——不是继承来的。
常见错误现象：<p>中文段落</p> 没写 lang="zh-Hans"，顿号按英文间距渲染；<pre class="brush:php;toolbar:false;" lang="bash"></pre> 在语言切换后被错误改成 lang="zh-Hans"，代码字体被中文字体覆盖；一段日文引文 <p lang="ja"></p> 跟着主语言一起切成了 lang="en"，读错语音。
- 所有含文本的语义化标签（
<h1></h1>、<p></p>、<section></section>、<footer></footer>）都必须显式写lang，值与当前语言包一致 - 已有
lang的特殊元素（如<pre class="brush:php;toolbar:false;" lang="bash"></pre>、<code lang="sql">）切换语言时保留原值，这是多语言混排的合法场景 - 局部混排内容（如英文术语、日文引用、代码块）必须显式加内联
lang，例如<code lang="en">useState - lang 值必须符合 BCP 47：用
zh-Hans，别用zh_CN或chinese；iOS VoiceOver 对ja支持差，得写ja-JP
lang 属性、每条 data-i18n 后缀、每个动态插入节点的触发时机，都落在正确的位置——漏一个，就可能在某个小众屏幕阅读器上读错整段话。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
