Lingo 检查

翻译未更新时让 CI 检查失败,并检查 React 消息目录。

翻译未更新时,lingo check 会判定检查失败。它会逐一将源文件与 .lingo/lock.json 比对,确认所有目标文件都存在;对于 @lingo.dev/react 项目,还会检查提取的消息目录、声明、上下文和翻译。

sh
lingo check --json

哪些检查会运行 #

检查运行条件
文件检查.lingo/config.json 中有 files,或项目不是 React 项目。
React 检查根目录下或离 --src 最近的 package.json 列出了 @lingo.dev/react、@lingo.dev/react-next 或 @lingo.dev/react-tanstack,或者生成的声明文件(默认为 lingo.d.ts)已存在。

配置了 files 的 React 项目会运行两种检查。如果没有任何 files 模式匹配到文件,检查会与 lingo push 一样报出 no-source-files 并失败;React 项目除外,此时只运行 React 检查,并在标准错误输出中说明。既未配置 files、又不是 React 项目的项目,会报出与 lingo push 相同的配置错误并失败。

lingo check 无需 API 密钥,也不会写入任何内容。除了可通过 DO_NOT_TRACK=1 关闭的 CLI 遥测,它不会发起任何网络请求。只要报告了问题或遇到配置错误(例如目标冲突或 Lockfile 损坏),退出码就是 1;否则为 0。

文件检查 #

源文件指 lingo push 会发送的文件。目标路径指推送操作为每个已配置的目标语言区域写入文件时使用的路径。

情况问题修复方法
源文件与对应的 Lockfile 条目一致,且目标文件均存在无
没有任何 files 模式匹配到文件no-source-files修正 files 模式
源文件自上次翻译后发生了变化source-changedlingo push --wait;如果推送仍在运行,则使用 lingo pull
源文件没有对应的 Lockfile 条目source-not-pushedlingo push --wait
目标文件缺失,源文件为最新版本missing-targetlingo push --backfill-missing --wait
目标文件缺失,源文件已更改或从未推送过missing-targetlingo push --wait
目标文件被手动编辑过无
没有 Lockfile,且所有目标文件均存在无,标准错误输出中会有提示
没有 Lockfile,且有目标文件缺失missing-target,标准错误输出中会有提示lingo push --backfill-missing --wait,然后提交目标文件和 .lingo/lock.json

如果某个路径已不再配置为源文件,其 Lockfile 条目会被忽略。lingo push 输出的目标推断警告和跳过 YAML 的警告,也会在这里通过标准错误输出显示。

解读问题 #

类型可尝试的修复方法
missing-context为提取的消息补充有用的上下文。
stale-jsonc重新生成并检查源消息目录。
stale-types重新生成声明,并将其纳入应用的类型检查。
missing-translation检查仍在使用、但没有非空有效目标值的键。
orphaned清理前,先确认消息是已被移除,还是在提取时被遗漏。

文件检查的问题及修复方法,请参阅文件检查。

JSON 输出 #

JSON 输出包含 issues 和 stats。供人阅读的输出会列出相同的问题,方便本地使用。

每个问题都包含 type 和 message。React 问题可能包含 src;文件问题包含 file,其中 missing-target 问题还包含 locale。

统计信息包含 messages、locales、missingContext、missingTranslations、orphaned、staleJsonc 和 staleTypes;未运行 React 检查时,这些值为零或假。语言区域数量包括发现的目标语言区域和源语言区域。运行文件检查后,stats.files 包含 lockfile、sources、locales、changedSources 和 missingTargets。这些数据反映的是一致性,并非实际测得的语言质量。

在 CI 中运行 #

对每个拉取请求或合并请求运行检查,包括来自派生仓库的请求:

yaml
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest check

使用与提取时相同的输入 #

--src、--out、--types 和 --source-locale 仅适用于 React 检查。--src 默认为 src,--source-locale 默认为 en。消息目录路径优先采用 --out,其次采用配置的路径,最后采用 locales;声明路径优先采用 --types,其次采用配置的路径,最后采用 lingo.d.ts。所有路径均以项目根目录为基准解析。源语言区域的默认值独立于本地化配置。--json 默认为假,适用于两种检查。

使用相同的输入运行提取,让过期内容恢复到最新状态。检查警告和差异后,重新运行检查并构建应用。只清理已确认不再使用的条目,随后重新生成声明。

限制 #

  • 文件检查以文件为单位。现有目标文件中缺少键的情况不会被报告,React .jsonc 消息目录除外。
  • 不会检查同一个共享消息目录(例如 .xcstrings 文件)内的语言区域;手动编辑其中的内容会被视为源文件变更。
  • 从 CLI 迁移到 GitHub App 的仓库应删除 .lingo/lock.json。
  • 遇到配置错误(例如两个源文件解析到同一个目标路径,或 Lockfile 损坏)时,会以退出码 1 退出,在标准错误输出中显示消息,不输出 JSON。
  • 源文件哈希值按字节精确计算,因此运行 lingo push 的 checkout 与 CI 中的 checkout 必须使用相同的行尾符。将 * text=auto eol=lf 添加到 .gitattributes。

对于 React 消息目录,目标文件指消息目录所在目录中的 .jsonc 文件。当 files 模式匹配到源消息目录(例如 locales/en.jsonc)时,每个已配置的目标语言区域文件也都必须存在。

只有缺少上下文的提取警告会转化为上下文问题。动态表达式警告和冲突信息在这里并不构成全面的失败判定条件;提取操作本身会在发生冲突时强制失败。非空的源语言占位文本即使不是翻译,也可能通过存在性检查。

如果只需确认生成内容的字节是否为最新状态,请使用 extract --check。使用此检查工具的同时,仍需进行原生格式验证和内容审核;检查通过并不能说明实际检查范围之外的 Android 资源、Markdown 渲染或翻译含义是否正确。