跳到正文
跳到正文

参考 / CLI

机器翻译页面

本页面为自动翻译,可能有错误或表述不够自然。内容以英文版本为准。阅读英文原文。

verbatra check

按语言环境报告哪些键缺失或过期,不写入文件也不调用提供商;任何语言环境不同步时让 CI 失败。

按目标语言环境报告有多少键缺失、过期或已是最新,并以 CI 步骤可以据此判断结果的退出码退出。check 运行 verbatra translate 在调用提供商之前所做的读取和比对,然后停止:不调用提供商,不写入文件,不需要 API 密钥。

用法

verbatra check [flags]

示例

# 译文漂移时让构建失败
verbatra check

# 两个语言环境的机器可读状态
verbatra check --locales de,fr --json

# 同时列出被翻译成多种译法的源字符串
verbatra check --consistency

# 占位符、内联标记和 ICU 损坏时失败,出现警告时也失败
verbatra check --qa --strict

# 机器译文还在等待批准时失败
verbatra check --require-reviewed

# 源中出现邮箱、API 密钥或银行卡号时失败
verbatra check --sensitive

# 检查编辑器或智能体刚更改的那一个文件
verbatra check --file locales/de.json --json

选项

选项参数默认值作用
--locales<list>所有已配置的目标只检查这个以逗号分隔的子集;未配置的语言环境以 UNKNOWN_LOCALE 失败,空列表以 INVALID_LOCALES 失败,两者的退出码都是 2
--consistency无关闭同时列出被翻译成多种译法的源字符串;仅作报告,见一致性报告
--qa无关闭同时对每条已提交的译文运行质量检查;出现错误时退出码为 1
--file<path>关闭只检查这个语言文件,见单个文件;不能与 --locales、--consistency、--require-reviewed 或 --sensitive 同用
--severityerror 或 warningwarning与 --qa 或 --file 同用时,报告的最低严重级别
--strict无关闭与 --qa 或 --file 同用时,出现警告或不完整的复数时退出码也为 1;不能与 --severity error 同用
--require-reviewed无关闭机器编写的译文尚未获批时,退出码也为 1
--sensitive无关闭同时扫描源文件和术语表中的敏感内容;出现任何检查结果时退出码为 1

同时接受全局选项 --cwd、--config 和 --json。

源中有、目标中没有的键是缺失的;其源字符串在上次翻译之后又更改的键是过期的。语言环境既无缺失也无过期时,即为同步。要查看计数背后的键列表,用 verbatra diff。

行为

纯文本输出:

输出
verbatra check
  de: 3 missing, 1 stale (1 protected), 38 up-to-date (out of sync)
  fr: 0 missing, 0 stale, 42 up-to-date (in sync)
out of sync (run verbatra translate to update)

一致性报告

--consistency 按目标语言环境,列出两个或更多键译法不同的每个源字符串:源文本、每种不同的译文,以及持有它的键。它从不更改退出码、值或审校队列。比较规则如下:

  • 比较的是经过 Unicode NFC 规范化、\r\n 折叠为 \n、并去掉首尾空白之后的值。内部空白和字母大小写都计入比较。
  • 只比较已是最新的键,与其自身的源相同的译文留给 EQUALS_SOURCE 处理。
  • 描述、含义、复数标志或 gettext msgctxt 不同的键,从不归为一组。
  • 复数形式按形式逐个比较:同一个键的 one 和 other 形式从不归到一起。

已知的误报:i18next 的上下文变体(invite_male、invite_female),标有 #, fuzzy 的 gettext 条目,不支持复数的格式(yaml、ngx-translate-json、xliff、properties、ini、resx)中带复数风格的键,以及 custom: 格式的复数形式。给这样的键设置不同的描述或含义,或者忽略该检查结果。使用 --json 时,每个语言环境都带有 inconsistencies: { source, context?, description?, meaning?, isPlural, pluralForm?, translations: [{ value, keys }] }[]。

受保护的键

由人工编写、导入或在 verbatra 之外更改的过期键,或匹配 pinnedKeys 的键,是 translate 留给人工处理的键(见保留人工翻译)。check 仍会统计它,并显示其中受保护的数量,例如 2 stale (1 protected)。--json 在每个语言环境中用 protected 字段给出该数量;verbatra.provenance.json 不可读时,只统计固定的键。

复数类别

每次 check 都会列出缺少目标语言所用 CLDR 复数类别的复数,例如只有 one 和 other 的波兰语 Android <plurals>:

输出
plural categories (warning: exit 1 only under --qa --strict)
  pl: 2 plurals missing CLDR categories
    cart {count} plural: missing few, many
    files: missing few, many

类别来自 Node.js 内置的 CLDR 规则(见语言与语言环境)。检查的格式:

格式读取的复数形式
i18next-json_one、_few 等键后缀,以及按序数规则检查的 _ordinal_ 复数
android-xml每个 <plurals> 的 <item quantity> 条目
apple-strings.strings 文件旁边 .stringsdict 中的复数规则
apple-xcstrings每个语言环境的 variations.plural 类别
next-intl-json、arb每个 ICU plural 和 selectordinal,包括嵌套的

other 始终是必需的。=1 这样的精确分支从不替代某个类别,select 分支从不检查,并且只检查目标中至少拥有一种形式的复数。它是警告:普通的 check 不会因此改变退出码,--qa --strict 则因它失败。verbatra doctor 报告同样的复数。使用 --json 时,每个语言环境都带有按键排序的 incompletePlurals:

interface IncompletePlural {
  code: "PLURAL_CATEGORIES_INCOMPLETE";
  key: string;              // 基础键,或 ICU 消息的键
  argument?: string;        // ICU 复数的参数,例如 count
  ruleType: "cardinal" | "ordinal";
  missing: ("zero" | "one" | "two" | "few" | "many" | "other")[]; // 按 CLDR 顺序
}

质量检查

--qa 把翻译运行对提供商输出所做的检查,应用于语言文件中已有的值,无论是否过期,包括目标语言需要的额外复数形式。检查结果分两种严重级别:

  • error:该值未通过完整性门禁,原因为 placeholder、markup、icu、degenerate 或 empty。详情把丢失的记号列为 -{{name}},把多出的列为 +{{nom}}。
  • warning:该值带有一个审校原因,由值、它的源和你的配置(术语表、maxLength)计算得出,因此不会有依赖提供商或缓存的原因;对 FOREIGN_PLACEHOLDER_CHANGED,检查结果的 details 会列出每个丢失或更改的记号,例如 -{name}。有错误的值不会再有警告。
输出
qa: 1 error, 1 warning
  de: 1 error, 1 warning in 42 values checked
    greeting: error placeholder (-{{name}}, +{{nme}})
    title: warning EQUALS_SOURCE

孤立的键和缺失的键会被跳过,不是有效 ICU 的源键在 invalidSourceKeys 下列出一次。受保护的、固定的和已拒绝的值与其他值一样接受检查。使用 --json 时,result.qa 保存总数,每个语言环境保存它自己的 qa:

interface CheckQaSummary { errors: number; warnings: number; invalidSourceKeys: string[]; limitsNotice?: { code: "LIMITS_FILE_IGNORED"; message: string } }
interface LocaleQaReport { checked: number; errors: number; warnings: number; findings: QaFinding[] }
type QaFinding =
  | { key: string; severity: "error"; reason: "placeholder" | "markup" | "icu" | "degenerate" | "empty"; details?: string[] }
  | { key: string; severity: "warning"; reason: string; details?: string[] }; // 上面的审校原因之一

要求译文已审校

当某个值的来源是 machine、memory、fuzzy 或 agent,且未在已提交的 verbatra.provenance.json 中获得批准时,--require-reviewed 以退出码 1 失败;Studio(见在 Studio 中审校)和 MCP 工具(见 verbatra mcp)把决定记录在这个文件中。源文本更改之前、或值更改之前给出的批准不算数。

输出
review: failed [REVIEW_REQUIRED] 2 machine-written translations not approved
  de: 2 unreviewed: checkout.title, checkout.total
  approve or reject them in verbatra studio's Review queue, then commit verbatra.provenance.json

使用 --json 时,result.review 是 { reviewed, unreviewed, code? },其中 code 是 REVIEW_REQUIRED,或在来源记录文件已损坏或来自更新版本的 verbatra 时是 REVIEW_STATE_UNREADABLE(此时门禁失败)。每个语言环境带有 review.unreviewed,即按源顺序排列的键。

敏感内容

--sensitive 对每个源键(键名、值、描述、含义)以及每个被检查语言环境的术语表,运行敏感内容防护的扫描,使用 sensitiveData 的检测器、模式和允许列表(没有该块时用默认检测器),无论它的 mode 和提供商是什么,包括 none:值仍会通过导出、XLIFF 和 TMX 交接离开本机。它报告键和检测器,除键名外从不报告匹配到的文本,出现任何检查结果时以退出码 1 失败。

email 检测器会跳过保留的示例域名,因此用看起来真实的地址来测试。

输出
sensitive: 1 key and 0 glossary terms hold content that looks sensitive
  support.contact: email in value
  remove it, list it in sensitiveData.allow, or turn the detector off in sensitiveData.detectors

使用 --json 时,result.sensitive 是 { findings, glossaryTerms },每条检查结果是 { key, fields, detectors };detectors 可能包含 pattern-timeout-<n>。

单个文件

--file <path> 检查一个语言文件,供编辑器和智能体在编辑后通过钩子调用。它读取该文件、verbatra.limits.json (无法使用时会被忽略,并在 stderr 上给出通知,与 --qa 下相同;doctor 会指出问题),以及(该文件属于目标语言环境时)源文件,除此之外不读取别的。路径相对于 --cwd 解析,并与 files.pattern 匹配,以找出它的语言环境。

  • 无法解析的文件是一个 syntax 错误,带适配器的错误码(INVALID_JSON、INVALID_YAML 等),解析器报告位置时还带行号和列号。
  • 目标文件按 --qa 检查,包括复数类别;源文件只检查语法。apple-xcstrings 消息目录文件会针对每个目标语言环境检查。
  • 路径不是任何已配置语言环境的文件时,以 NOT_A_LOCALE_FILE 和退出码 2 失败。

使用 --json 时,result 复用 --qa 的报告,因此钩子只需解析一种结构:

interface CheckFileSummary {
  file: string;                          // 相对于项目根目录
  role: "source" | "target" | "catalogue";
  locales: {
    locale: string;
    incompletePlurals: IncompletePlural[];
    qa: { checked: number; errors: number; warnings: number; findings: (QaFinding | QaSyntaxFinding)[] };
  }[];
  qa: CheckQaSummary;
}
interface QaSyntaxFinding {
  severity: "error"; reason: "syntax"; code: string; message: string;
  line?: number; column?: number;       // 解析器报告位置时给出,从 1 开始计数
}

缺失的键和过期的键不属于文件检查的内容。

JSON 输出

Schema:check-envelope.json 校验整个信封(envelope);其他 schema 见 Schema。

--json 输出一个信封,其 result 是状态文档。没有 --qa、--require-reviewed 或 --sensitive 时,inSync 恰好在命令以 0 退出时为真:

interface CheckSummary {
  inSync: boolean;
  locales: LocaleCheckSummary[];
  qa?: CheckQaSummary;          // 仅在使用 --qa 时
  review?: CheckReviewSummary;  // 仅在使用 --require-reviewed 时
  sensitive?: CheckSensitiveSummary; // 仅在使用 --sensitive 时
}

interface LocaleCheckSummary {
  locale: string;
  missing: number;              // 源中有,目标中没有
  stale: number;                // 源在上次翻译之后已更改
  upToDate: number;
  inSync: boolean;              // missing === 0 && stale === 0
  emptySource?: number;         // 源值为空:从不算缺失或过期
  provenance?: ProvenanceSummary; // 按来源和审校状态的计数
  protected?: number;
  incompletePlurals?: IncompletePlural[];
  inconsistencies?: InconsistencyGroup[]; // 仅在使用 --consistency 时
  qa?: LocaleQaReport;          // 仅在使用 --qa 时
  review?: LocaleReviewReport;  // 仅在使用 --require-reviewed 时
}

源键的值为空或只有空白,例如 extract 添加时没有默认值的键,暂时没有可翻译的内容:它计入 emptySource,而不是 missing 或 stale,从不让语言环境变成不同步,终端输出会指出这个数量。

终端反馈

check 在 stderr 上显示 verbatra: checking the locales... done (0.1s),使用 --file 时显示 verbatra: checking locales/de.json...。--quiet 会去掉它。见终端输出。

退出码

退出码含义
0已同步,且所给选项没有把任何检查结果变成失败
1某个语言环境有缺失或过期的键,--qa 或 --file 发现了错误(在 --strict 下还包括警告或不完整的复数),--require-reviewed 发现了未获批准的译文,或 --sensitive 发现了敏感内容
2无法运行:整个运行的错误,例如 SOURCE_UNREADABLE 或 NOT_A_LOCALE_FILE,或用法错误,例如 INVALID_QA_OPTION、INVALID_SEVERITY,以及 --file 为空或与 --locales、--consistency、--require-reviewed 或 --sensitive 同用时的 INVALID_OPTION

退出码 1 表示结果不干净,不表示运行失败;报告仍会输出。在源文件尚未就位的项目上,verbatra doctor 仍会给出报告。约定见退出码。

相关内容

在 GitHub 上编辑

本页内容