词库必须扁平化设计，键名全局唯一且按功能+语义命名；语言包加载需校验http状态与mime类型；动态dom插入后须手动触发翻译；多语言混排时lang属性需显式设置到语义容器；词库变更需绑定git提交记录。
词库结构必须扁平，键名全局唯一
大规模项目里最常踩的坑，是把语言包设计成嵌套对象（比如 {"common": {"button": {"submit": "提交"}}}），导致不同模块引用同一键时路径不一致、翻译遗漏或覆盖错乱。键名一旦带层级，就等于把结构耦合进词库，后续增删字段、跨模块复用都变困难。
实操建议：
- 所有语言文件（
zh.json、en.json等）只用一层键值对，例如"btn_submit": "提交"，而非"common.btn.submit" - 键名按功能+语义命名，避免纯数字或缩写（如不用
"b1"，而用"form_error_required_field"） - 新增键必须同步写入所有语言文件，缺失键统一 fallback 到
en，但空字符串""要保留——否则 JS 查不到 key 会留白，而不是退到英文
加载时校验 MIME 类型和 HTTP 状态
大规模项目部署后，语言包 404 或返回 HTML 错误页却静默失败，是线上文案大面积消失的主因。浏览器不会报错，fetch() 拿到非 JSON 响应后直接 resolve，后续 response.json() 才 throw，但很多人没包 try/catch。
实操建议：
- 语言包路径固定为
./locales/${lang}.json，不要拼接变量或用相对路径别名 - fetch 后必须检查
response.ok和response.headers.get('content-type')?.includes('application/json') - 服务端 Nginx/Apache 配置要确保
.json文件返回Content-Type: application/json，否则即使文件存在也会被当文本处理
动态插入的 DOM 必须手动触发翻译
词库再全也没用，如果弹窗、表格行、懒加载区块插入后没调用翻译函数，它们的 data-i18n 就是摆设。框架组件（如 Lit、React）有生命周期钩子可监听，但原生 DOM 或 jQuery 项目极易漏掉这步。
实操建议：
- 封装一个
translateElement(el)函数，遍历el.querySelectorAll('[data-i18n]')并更新 textContent/attributes - AJAX 插入内容后立即执行
translateElement(insertedNode)，不是等整个页面重刷 - 避免在
document.addEventListener('DOMContentLoaded', ...)里只扫一次 body——后续动态节点永远不进翻译队列
多语言混排场景下 lang 属性不能继承
大规模项目常有代码块、术语、引文夹杂英文，但只改 document.documentElement.lang，这些局部内容仍被屏幕阅读器读作中文、标点间距错乱、等宽字体套用中文字体。这不是 bug，是浏览器行为规范。
实操建议：
- 所有含文本的语义化容器（
<h2></h2>、<p></p>、<section></section>）都显式设lang，值与当前语言包一致 - 已有
lang的元素（如<pre class="brush:php;toolbar:false;" lang="bash"></pre>）切换语言时保留原值，不覆盖——这是明确的多语言混排，不是错误 -
<script></script>和<style></style>里设lang无效，删掉，它们不参与渲染
"dashboard_title" 为什么从“仪表盘”改成“控制台”。这问题没法靠工具解决，得靠流程。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
