最轻量且工具链友好的未翻译内容标记方式是直接使用data-i18n-pending属性，基础写法为用户尚未登录或带key的用户尚未登录，值为"true"或不设值均有效，避免用false/resolved、注释、占位符及非渲染节点。
直接用 data-i18n-pending 属性标记，不加额外逻辑、不改构建流程、不影响渲染——这是目前最轻量且工具链友好的方式。
怎么写 data-i18n-pending 才算有效
它不是注释，也不是占位符，而是一个可被扫描、可被样式干预、可被 CI 检查的正式标记。
- 基础写法：
<p data-i18n-pending="true">用户尚未登录</p>—— 值为"true"或不设值（即data-i18n-pending）都算待处理 - 推荐带 key 写法：
<p data-i18n-pending="auth.login.message">用户尚未登录</p>—— 方便后续定位、去重、与语言包键名对齐 - 别用
data-i18n-pending="false"或data-i18n-pending="resolved"，这些不会被常规脚本识别，反而干扰 grep 检查 - 不要嵌套在
<script></script>、<style></style>或注释里——这些节点不参与 DOM 渲染，标记了也扫不到
开发阶段如何快速发现漏标的节点
靠肉眼扫页面效率低，且容易忽略动态插入内容。用 CSS 临时高亮是最直接的办法。
- 在 DevTools 控制台粘贴执行：
document.querySelectorAll('[data-i18n-pending]').forEach(el => el.style.border = '2px dashed #ff6b6b') - 若想持久生效（仅限本地开发），在 dev 环境样式表中加：
[data-i18n-pending] { outline: 2px dashed #ff6b6b !important; } - 避免用
background-color—— 可能遮盖原有背景色，导致文字不可见 - Shadow DOM 中的节点需手动遍历：
shadowRoot.querySelectorAll('[data-i18n-pending]')，普通 CSS 选不到
CI 流程里怎么卡住未翻译内容合入
不能只靠人眼检查，必须让机器自动拦截。关键不是“有没有标记”，而是“有没有残留的待处理标记”。
- 简单检查（适合起步）：
grep -r 'data-i18n-pending' src/ | grep -v 'false\|resolved'—— 但会漏掉值为空或含空格的情况 - 可靠检查（推荐）：用
cheerio解析 HTML，查找所有data-i18n-pending属性值为"true"、""或未设值的元素 - 构建策略建议设为 warn 而非 error —— 避免紧急发布被阻塞；严重项目可升级为 error，但需配套快速修复通道
- 注意 SSR 页面要检查最终生成的 HTML 字符串，不是 JSX 或模板源码 —— 否则可能漏掉服务端渲染出的遗漏节点
和 i18n 工具链怎么真正配合上
标记只是第一步，关键是工具能识别并联动。很多团队标了却没效果，问题常出在“标得工具看不懂”。
- 如果你用
i18next或vue-i18n，确认其插件是否支持data-i18n-pending—— 不支持就得自己写扫描脚本，或改用框架原生 pending 机制 - 别指望构建工具自动删掉这个属性 —— 它应始终保留在生产 HTML 中，作为线上 debug 和 QA 验收依据
- 语言包补全后，不要手动删属性，而是把值改为
data-i18n-pending="false"或移除该属性 —— 便于审计哪些是已处理、哪些是新引入 - 动态插入的 DOM（如弹窗、表格行）插入后必须立即检查是否带
data-i18n-pending，否则上线后就变成“隐形遗漏”
最容易被忽略的是：标记本身不解决翻译问题，它只暴露问题。真正闭环在于——谁负责补语言包、谁验证渲染效果、谁清理标记、谁在 CI 里兜底。四个角色缺一不可，光靠前端加属性，迟早漏。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
