本文へスキップ
本文へスキップ

リファレンス / CLI

機械翻訳されたページ

このページは自動翻訳のため、誤りや不自然な表現が含まれている可能性があります。正式な内容は英語版です。英語の原文を読む。

verbatra types

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

キーのつづり間違いや、補間引数の指定漏れを、コンパイルエラーにします。types は、設定されたフォーマットアダプター(フォーマットを参照)を通してソースカタログを読み、宣言ファイルを 1 つ書き込みます。宣言には、すべてのキーのユニオン型と、キーごとにメッセージが受け取る引数が含まれます。プロバイダーは呼び出さず、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 のタプル。引数 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 とは意図的に区別されています。

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 で宣言の正しさを保つ

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

verbatra-types.d.ts text eol=lf

JSON 出力

スキーマ:types-envelope.json がエンベロープ(envelope)全体を検証します。ほかのスキーマはスキーマに一覧があります。

--json を付けると、エンベロープに 1 つの結果が入ります。

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 で編集

このページの内容