设计师必须将每个可翻译文本块明确标注为语义化data-i18n键名（如order.submit），图层名与键名严格一致，并单独标注placeholder/title/alt等属性对应后缀，含HTML结构文案需在语言包中提供可信片段。
设计师怎么给文案打标才不被开发漏掉
设计师不能只在 Figma 里写“中文/英文切换”，得把每个可翻译文本块明确标注为 data-i18n 键名，并同步输出结构化清单。比如按钮文案“提交订单”要标成 order.submit，而不是“submit_btn”或“zh_001”。
常见错误现象：设计师用颜色/图层分组代替语义标记，开发靠肉眼猜键名，结果 en.json 里写的是 checkout.button，而 HTML 里写的是 data-i18n="pay_now"，加载后留空。
- 所有文案必须出现在 Figma 的文本图层属性面板中，且图层名与
data-i18n值严格一致（如图层名 =header.logo_text） - 占位符（placeholder）、提示文字（title）、图片替代文本（alt）需单独标注，对应加后缀：
data-i18n-placeholder、data-i18n-title、data-i18n-alt - 含 HTML 结构的文案（如“请阅读服务条款”）必须在语言包中提供完整可信片段，且设计师要注明该字段允许内联标签
前端怎么确保每次构建都校验语言包完整性
语言包缺失 key 是上线后大面积空白的主因。不能靠人眼核对，得在构建流程里加校验脚本，检查所有 locales/*.json 是否键名完全一致。
性能影响：全量 diff 每个 JSON 文件会拖慢 CI，建议只比对键名集合，不比值；同时跳过注释和空格差异。
立即学习“前端免费学习笔记（深入）”；
- 用
jq提取各语言文件键名并排序比对：jq 'keys_unsorted | sort' locales/en.json和locales/zh.json输出应完全相同 - Webpack 构建时通过
html-webpack-plugin的templateParameters注入语言数据，若某 key 缺失，直接throw new Error中断构建 - CI 流程中增加
npm run i18n:check脚本，失败则不生成 HTML 输出，避免带残缺语言包发布
后端怎么和前端共享语言检测逻辑
前后端语言判断不一致，会导致 SSR 渲染错语言、SEO 抓取错版本、用户首次访问看到中文但 URL 是 /en/ —— 这不是 bug，是架构断裂。
关键点在于：浏览器 navigator.language 不可靠，localStorage 可能过期，唯一可信来源是 HTTP 请求头里的 Accept-Language。
- Node.js 后端用
accepts库解析Accept-Language: zh-CN,zh;q=0.9,en-US;q=0.8，得出首选语言码（如zh-Hans），注入到 HTML 的<html lang="zh-Hans">和全局变量window.__LOCALE__ = "zh-Hans" - 前端初始化时优先读
document.documentElement.lang，fallback 到window.__LOCALE__，最后才是navigator.language—— 顺序错了就可能覆盖服务端决策 - 用户手动切换语言时，必须发 POST 到
/api/locale同步服务端偏好，否则后续 API 返回的错误消息仍是旧语言
为什么多语言页面的 DOM 更新必须绕过 innerHTML
用 element.innerHTML = translatedText 替换带事件的按钮或已初始化的组件，会清空绑定的监听器、重置表单控件状态、销毁第三方库实例（如日期选择器）。这不是“换文字”，是“炸掉再重建”。
容易踩的坑：以为加了 data-i18n 就万事大吉，结果切换语言后按钮点击失效、输入框内容消失、滚动位置跳回顶部。
- 默认走
element.textContent = translatedText，安全、轻量、不破坏 DOM 状态 - 仅当文案含 HTML（如强调词 必填）时，才用
element.innerHTML，但必须提前过滤或白名单校验，禁止执行 script、href=javascript: 等危险内容 - 切换前用
getComputedStyle(element).scrollTop记录滚动偏移，更新完再element.scrollTop = oldScrollTop，否则列表页一换语言就回到顶部
data-i18n 扫描到，必须显式调用翻译函数。 
