---
title: "verbatra types"
description: "カタログのキーとメッセージの引数の TypeScript 宣言を生成します。プロバイダーは呼び出さず、API キーも読み込みません。"
type: "reference"
---
# verbatra types

カタログのキーとメッセージの引数の TypeScript 宣言を生成します。プロバイダーは呼び出さず、API キーも読み込みません。

<AvailableFrom version="0.11.0" />

キーのつづり間違いや、補間引数の指定漏れを、コンパイルエラーにします。`types` は、設定されたフォーマットアダプター（[フォーマット](https://verbatra.kreitz-webdev.de/ja/docs/formats.md)を参照）を通してソースカタログを読み、宣言ファイルを 1 つ書き込みます。宣言には、すべてのキーのユニオン型と、キーごとにメッセージが受け取る引数が含まれます。プロバイダーは呼び出さず、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/ja/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` のタプル。引数 1 つにつき 1 つの位置 |
| 一部の `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` |
| 同じ 3 つのフォーマットの 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"` のリソース）は宣言されず、出力に示されます。

### 名前自体にドットを含むキー [#名前自体にドットを含むキー]

宣言されるキーは、i18n ライブラリが理解する検索構文ではなく、verbatra が `verbatra.lock.json` で表記するとおりに書かれます。`{"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"` のような壊れた値からプレースホルダーが得られません。そのため、メッセージは引数を取らないものとして宣言され、本当に必要な引数を渡すとコンパイルエラーになります。何も検出していないため、何も報告されません。修正するのは宣言ではなく、カタログです。

### 複数形のキー [#複数形のキー]

複数形のキーを 1 つにまとめることはしません。i18next は複数形をキーの接尾辞で表します。そのため、`cart.item_one` と `cart.item_other` は書かれたとおりに宣言されます。その隣には、`t("cart.item", { count })` が参照するベースキー `cart.item` も宣言され、`count` と、いずれかの形が取るすべての引数を必須にします。i18next 自身の型も、両方の書き方を受け付けます。`place_ordinal_one` のような序数のグループは `place` を宣言し、カタログにすでにあるベースキーは、それ自身の宣言を保ちます。`VerbatraPluralMessageKey` には、アダプターが複数形を持つと印を付けたキー（接尾辞付きのもの）が一覧されます。それらに絞り込めます。

### 宣言の出力先 [#宣言の出力先]

デフォルトでは、プロジェクトルートの `verbatra-types.d.ts` に書き込まれます。**このファイルをコミットしてください**。チームメンバーや CI のジョブは、verbatra を実行せずに、これに対して型チェックできます。また `--check` には、比較対象となるコミット済みのファイルが必要です。`.gitignore` には何も追加されません。

次のいずれかに当たる出力パスは、`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` が既存のファイルを拒否することはありません。すべてのチェックを通ったパスでも、書き込み中に失敗することがあります（読み取り専用のディレクトリ、ディスクが満杯など）。その場合、実行はファイルと `EACCES` などのファイルシステムのコードを示して、`TYPES_UNWRITABLE` で止まります。

### CI で宣言の正しさを保つ [#ci-で宣言の正しさを保つ]

同じジョブで、[`verbatra check`](https://verbatra.kreitz-webdev.de/ja/docs/cli/check.md) の隣に `types --check` を置いて実行します。`check` はロケールがソースに遅れるドリフトを、`types --check` は型がソースに遅れるドリフトを検出します。比較はバイト単位で、宣言は常に LF の改行で書き込まれます。そのため `.gitattributes` で改行を固定してください。固定しないと、改行を書き換えるチェックアウトによって、ファイルがずっと古い状態のままになります。

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

### JSON 出力 [#json-出力]

スキーマ：[`types-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/types-envelope.json) がエンベロープ（envelope）全体を検証します。ほかのスキーマは[スキーマ](https://verbatra.kreitz-webdev.de/ja/docs/cli/output.md#スキーマ)に一覧があります。

`--json` を付けると、[エンベロープ](https://verbatra.kreitz-webdev.de/ja/docs/cli/output.md#json-出力)に 1 つの結果が入ります。

```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/ja/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/ja/docs/cli/output.md#終了コード)を参照してください。

## 関連項目 [#関連項目]

- [`verbatra extract`](https://verbatra.kreitz-webdev.de/ja/docs/cli/extract.md)：コードが使うキーをカタログに追加します。`types` はそれらを宣言します。
- [`verbatra check`](https://verbatra.kreitz-webdev.de/ja/docs/cli/check.md)：ロケールのドリフトに対する CI のゲートです。このコマンドは型のドリフトを扱います。
- [フォーマット](https://verbatra.kreitz-webdev.de/ja/docs/formats.md)：各フォーマットが使うプレースホルダー構文を一覧にしています。
- [終了コードと JSON 出力](https://verbatra.kreitz-webdev.de/ja/docs/cli/output.md)：エンベロープと終了コードの規約を説明しています。
