跳到正文
跳到正文

参考 / CLI

机器翻译页面

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

verbatra types

为消息目录的键及其消息参数生成 TypeScript 声明,不调用提供商,也不读取 API 密钥。

把拼错的键或遗漏的插值参数变成编译错误。types 通过已配置的格式适配器(见格式)读取源消息目录,并写出一个声明文件:包含所有键的联合类型,以及每个键的消息所需的参数。它不调用提供商,不读取 API 密钥,也从不触碰目标语言文件。

用法

verbatra types [flags]

示例

# write verbatra-types.d.ts from the source catalog
verbatra types

# write it where the app already imports from
verbatra types --out src/generated/messages.d.ts

# CI gate: exit 1 if the committed declaration is stale
verbatra types --check

# machine-readable result for a script
verbatra types --json

选项

选项参数默认值作用
--out<path>verbatra-types.d.ts声明的写入位置,相对于工作目录,且位于项目根目录之内;缺失的目录会创建
--check无关闭把已提交的声明与重新生成的内容逐字节比较,不写入任何内容;声明已过期或缺失时以 1 退出

此命令还接受全局选项 --cwd、--config 和 --json。

行为

它生成什么

给定这样一个 locales/en.json:

{
  "app": { "title": "Verbatra" },
  "greeting": "Hello {{name}}",
  "cart": { "item_one": "{{count}} item", "item_other": "{{count}} items" }
}

你会得到:

// Generated by verbatra from locales/en.json (i18next-json). Do not edit by hand.
// Re-run `verbatra types` after the source catalog changes.

/** An argument whose type the source catalog does not record. */
export type VerbatraArgument = string | number;

/** The arguments of a message that takes none: passing any argument is a type error. */
export type VerbatraNoArguments = Record<string, never>;

/**
 * The arguments of a message verbatra could not analyse, so nothing is claimed about them.
 * Every key carrying this type is listed by `verbatra types` when it generates this file.
 */
export type VerbatraUnknownArguments = Record<string, VerbatraArgument>;

/** Every key in the source catalog, mapped to the arguments its message takes. */
export interface VerbatraMessages {
  "app.title": VerbatraNoArguments;
  "greeting": { readonly "name": VerbatraArgument };
  "cart.item": { readonly "count": VerbatraArgument };
  "cart.item_one": { readonly "count": VerbatraArgument };
  "cart.item_other": { readonly "count": VerbatraArgument };
}

/** Every key in the source catalog. */
export type VerbatraMessageKey = keyof VerbatraMessages;

/** The arguments the message at `Key` takes. */
export type VerbatraMessageArguments<Key extends VerbatraMessageKey> =
  VerbatraMessages[Key];

/** The keys the source catalog marks as carrying plural forms. */
export type VerbatraPluralMessageKey = "cart.item_one" | "cart.item_other";

按它为你自己的翻译函数标注类型,其余交给编译器:

import type { VerbatraMessageArguments, VerbatraMessageKey } from "./verbatra-types.js";

declare function t<Key extends VerbatraMessageKey>(
  key: Key,
  args: VerbatraMessageArguments<Key>,
): string;

t("greeting", { name: "Ada" }); // fine
t("greting", { name: "Ada" });  // error: not a key in the catalog
t("greeting", {});              // error: the name argument is required
t("app.title", { name: "Ada" }); // error: this message takes no argument

它会声明什么,不会声明什么

键与格式适配器产生的完全一致,按文档顺序排列,所以同一个消息目录总是产生相同的字节。参数来自适配器提取的占位符记号;next-intl-json 和 arb 的消息用适配器的 ICU 解析器读取,所以只有部分分支使用的参数仍会被声明。没有任何内容靠猜测,也没有任何内容声明为 any。

你的消息声明的内容
没有占位符VerbatraNoArguments,所以传入任何东西都是类型错误
具名占位符({{name}}、{name}、%(name)s)带这些名称的对象形状
编号或匿名占位符({0}、%@、%1$d)readonly 元组,每个参数占一个位置
只有部分 select 或 plural 分支使用的参数(next-intl-json、arb)可选成员 name?:,或末尾的可选元组位置([number, VerbatraArgument?]);每个分支都使用的参数仍为必填
next-intl-json 或 arb 中的 ICU number、plural 或 selectordinal 参数number
next-intl-json 或 arb 中的 ICU date 或 time 参数({d, date, short})Date | number
next-intl-json 或 arb 中的 ICU select 参数({gender, select, ...})string
i18next-json、ngx-translate-json 或 yaml 中的 i18next number 格式化器({{count, number}})number
这三种格式中的 i18next datetime 格式化器({{d, datetime}})Date | number
i18next 的未转义插值({{- name}})前缀之后的名称 name
properties 中的 MessageFormat number、plural 或 choice 参数({0,number})number
数字类的 printf 转换(%d、%1$d)number
字符串类的 printf 转换(%s、%(name)s)string
其他任何占位符,包括普通的 ICU 参数({name})VerbatraArgument,即 string | number 的别名
无效的消息语法,只有 next-intl-json 和 arb 会检查VerbatraUnknownArguments,并且输出中会列出该键
混用具名、编号和匿名参数的消息VerbatraUnknownArguments,并且输出中会列出该键
位置小于 0 或不小于 64 的编号参数(%0$s、{64})VerbatraUnknownArguments,并且输出中会列出该键

占位符没有名称的格式(Apple .strings、Android strings.xml、按位置的 gettext 转换)得到元组,从不虚构名称。同一个名称用于不同类型时,得到这些类型的联合:{d, date, short} 与普通的 {d} 并存时,变为 Date | number | string。键始终是带引号的字符串字面量,所以含有点号、保留字、前导数字或引号的键会原样声明。适配器排除在翻译之外的键(非字符串的叶子节点、Android 的 translatable="false" 资源)永远不会声明,并且会在输出中列出。

键名本身含有点号的情况

声明的键按 verbatra 在 verbatra.lock.json 中的写法拼写,而不是按你的 i18n 库能理解的查找语法拼写。包含 {"a.b": "..."} 的 JSON 消息目录,其键为 a\.b,有意与嵌套路径 a.b 区分开:

export interface VerbatraMessages {
  "a\\.b": VerbatraNoArguments;
}

i18next 对它的键分隔符没有转义方式,所以 t("a\\.b") 查不到该键。如果你的消息目录含有这类键,把 keySeparator 设为其他字符(扁平的消息目录则设为 false),并在你自己的带类型封装中,把声明的键映射到运行时的键。

声明有误而不只是沉默的唯一情况

只有 next-intl-json 和 arb 会校验消息语法。在其他每种格式中,损坏的值(例如 "Hello {name")不会产生占位符记号,所以该消息被声明为不需要参数,传入它真正需要的参数反而是编译错误。没有任何东西会报告它,因为没有任何东西检测到它。要修的是消息目录,而不是声明。

复数键

没有任何内容被合并。i18next 把复数作为键后缀携带,所以 cart.item_one 和 cart.item_other 按原样声明,并且在它们旁边声明基础键 cart.item,即 t("cart.item", { count }) 查找的键,它要求 count 以及任一形式所需的每个参数。i18next 自己的类型也接受这两种写法。序数组(例如 place_ordinal_one)声明 place,而消息目录中已有的基础键保留它自己的声明。VerbatraPluralMessageKey 列出适配器标记为带复数形式的键,即带后缀的那些,供你缩小范围。

声明写到哪里

默认写入项目根目录的 verbatra-types.d.ts。请提交它:同事或 CI 作业无需运行 verbatra 就能对它做类型检查,--check 也需要已提交的文件来比较。没有任何东西把它加入 .gitignore。

以下情况下,types 以 TYPES_OUTPUT_CONFLICT 拒绝该输出路径:

  • 没有指向文件,包括以路径分隔符结尾的路径,例如 generated/(空的 --out 会更早以 INVALID_OUT 失败);
  • 是绝对路径;
  • 用 .. 越出项目根目录;
  • 不是 TypeScript 文件,也就是名称不以 .ts、.mts 或 .cts 结尾;
  • 指向已配置的语言文件(源或目标),所以生成永远不会覆盖消息目录;
  • 是锁文件 verbatra.lock.json;
  • 是来源记录文件 verbatra.provenance.json;
  • 是翻译记忆库缓存 verbatra.cache.json;
  • 是 verbatra 用来查找配置的文件:package.json、.verbatrarc、.verbatrarc.json、.verbatrarc.yaml、.verbatrarc.yml、.verbatrarc.js、.verbatrarc.cjs、.verbatrarc.ts、verbatra.config.js、verbatra.config.cjs 或 verbatra.config.ts;
  • 是本次运行实际加载的配置文件,包括你用 --config 指定的文件;
  • 是你的配置中 glossary 所指向的术语表文件;
  • 是已存在的文件,但不以 verbatra 写在每个声明顶部的 // Generated by verbatra from 头行开头(开头的字节顺序标记和空行会被忽略),或文件太大而无法校验。

文件名的比较不区分大小写,符号链接解析之后会再检查一次,所以带链接的目录无法把声明带到项目根目录之外或受保护的文件上。最后一项检查只在运行将要写入时执行,并且不会动你的文件;--check 从不拒绝已存在的文件。通过全部检查的路径仍可能在写入时失败(只读目录、磁盘已满):运行以 TYPES_UNWRITABLE 停止,并给出文件和文件系统错误码(例如 EACCES)。

在 CI 中保持声明可信

在同一个作业中,把 types --check 放在 verbatra check 旁边运行:check 发现语言文件落后于源,types --check 发现你的类型落后于源。比较是逐字节的,而声明始终使用 LF 换行符写入,所以请在 .gitattributes 中固定换行符,否则签出时改写换行符会让该文件永久处于过期状态:

verbatra-types.d.ts text eol=lf

JSON 输出

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

使用 --json 时,信封包含一个结果:

interface GenerateTypesResult {
  path: string;               // absolute path of the declaration file
  sourcePath: string;         // the source catalog, relative to the project root
  keys: number;               // how many keys are declared
  withArguments: number;      // keys taking at least one determined argument
  unresolved: { key: string; reason: "invalid-message-syntax" | "mixed-argument-styles" | "argument-index-out-of-range" }[];
  excluded: string[];         // keys the adapter excluded, never declared
  plural: string[];           // keys carrying plural forms
  written: boolean;           // false under --check and when the file already matched
  stale: boolean;             // the file on disk differed when the run started
  missing: boolean;           // no file existed when the run started
  check: boolean;             // whether this was a --check run
}

终端反馈

摘要输出到 stdout;加载动画(spinner)行以及写入之后提示提交该文件的一行输出到 stderr(--check 不给出任何建议,--quiet 会去掉这两者)。下面依次是一次生成的运行、一次未更改的重新运行,以及一次过期的 --check:

输出
verbatra: generating the declarations... done (0.2s)
verbatra types
  214 keys declared, 63 of them taking arguments, from locales/en.json
  arguments not determined (1):
    legal.notice  invalid-message-syntax
  excluded by the adapter (1): meta.version
  wrote verbatra-types.d.ts
next: commit verbatra-types.d.ts (verbatra types --check compares against it in CI)

verbatra types
  214 keys declared, 63 of them taking arguments, from locales/en.json
  unchanged verbatra-types.d.ts

verbatra types
  215 keys declared, 63 of them taking arguments, from locales/en.json
  verbatra-types.d.ts is out of date, re-run verbatra types

颜色、加载动画以及控制它们的变量,见终端输出。

退出码

退出码含义
0已生成声明,无论文件是否有更改;或 --check 发现声明是最新的
1--check 发现已提交的声明已过期或缺失(is missing, run verbatra types to create it)
2无法运行:用法错误、配置或源问题、被拒绝的输出路径(TYPES_OUTPUT_CONFLICT),或无法写入的声明(TYPES_UNWRITABLE)

每个命令都遵循的约定见退出码。

相关内容

  • verbatra extract 把代码用到的键添加到消息目录;types 再声明它们。
  • verbatra check 是针对语言文件漂移的 CI 门禁,与这里针对类型漂移的门禁并列。
  • 格式列出每种格式使用的占位符语法。
  • 退出码与 JSON 输出介绍信封和退出码约定。
在 GitHub 上编辑

本页内容