---
title: "verbatra types"
description: "为消息目录的键及其消息参数生成 TypeScript 声明，不调用提供商，也不读取 API 密钥。"
type: "reference"
---
# verbatra types

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

<AvailableFrom version="0.11.0" />

把拼错的键或遗漏的插值参数变成编译错误。`types` 通过已配置的格式适配器（见[格式](https://verbatra.kreitz-webdev.de/zh-CN/docs/formats.md)）读取源消息目录，并写出一个声明文件：包含所有键的联合类型，以及每个键的消息所需的参数。它不调用提供商，不读取 API 密钥，也从不触碰目标语言文件。

## 用法 [#用法]

```bash
verbatra types [flags]
```

## 示例 [#示例]

```bash
# 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` 退出 |

此命令还接受[全局选项](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli.md#全局选项) `--cwd`、`--config` 和 `--json`。

## 行为 [#行为]

### 它生成什么 [#它生成什么]

给定这样一个 `locales/en.json`：

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

你会得到：

```ts
// 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";
```

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

```ts
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` 区分开：

```ts
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 中保持声明可信 [#在-ci-中保持声明可信]

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

```text
verbatra-types.d.ts text eol=lf
```

### JSON 输出 [#json-输出]

Schema：[`types-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/types-envelope.json) 校验整个信封（envelope）；其他 schema 见 [Schema](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md#schema)。

使用 `--json` 时，[信封](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md#json-输出)包含一个结果：

```ts
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
}
```

### 终端反馈 [#终端反馈]

<AvailableFrom version="0.12.0" />

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

```text output
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
```

颜色、加载动画以及控制它们的变量，见[终端输出](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md#终端输出)。

## 退出码 [#退出码]

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

每个命令都遵循的约定见[退出码](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md#退出码)。

## 相关内容 [#相关内容]

- [`verbatra extract`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/extract.md) 把代码用到的键添加到消息目录；`types` 再声明它们。
- [`verbatra check`](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/check.md) 是针对语言文件漂移的 CI 门禁，与这里针对类型漂移的门禁并列。
- [格式](https://verbatra.kreitz-webdev.de/zh-CN/docs/formats.md)列出每种格式使用的占位符语法。
- [退出码与 JSON 输出](https://verbatra.kreitz-webdev.de/zh-CN/docs/cli/output.md)介绍信封和退出码约定。
