メッセージ呼び出しの型をチェックする

宣言を生成して組み込み、編集中にソース文字列、コンテキスト、メッセージの値をチェックします。

メッセージ呼び出しは、TypeScriptとして正しくても、意図しないカタログ項目を要求していることがあります。コンテキストの変更やプレースホルダーのスペルミスにより、ソーステキストや{name}がそのまま画面に表示される場合があります。抽出処理では、既知のソースメッセージをアプリケーションの型システムに組み込むための宣言が生成されます。

宣言を生成して組み込む #

CLIをインストールしたら、次を実行します。

sh
npx lingo extract --src src --source-locale en

既定の出力はlocales/en.jsoncとlingo.d.tsです。既存のパターンでlingo.d.tsが対象になっていない場合は、アプリケーションの既存のtsconfigのインクルードリストに追加します。他の項目はそのまま残してください。

json
{
  "include": ["src", "lingo.d.ts"]
}

アプリケーションで通常使用している型チェックを実行します。宣言がコンパイラのプロジェクトに含まれていなければ、呼び出しに制約は適用されません。抽出時に--typesまたはi18n.typesPathを使用している場合は、代わりに実際の出力先パスを含めてください。

生成されるインターフェースの意味 #

このファイルは、ソース文字列とそのオプションを追加してLingoMessagesを拡張します。生成される構造の例を次に示します。

ts
export {};

declare module "@lingo.dev/react" {
  interface LingoMessages {
    "Hello, {name}.": {
      values: { name: string | number };
      context: "Greeting on the account dashboard";
    };
    "Save": {
      context: "Submit settings" | "Bookmark an article";
    };
  }
}

この例を手作業で更新し続けるのではなく、ファイルを再生成してください。今は、挨拶メッセージにvalues.nameと抽出されたコンテキストが必須になっています。Saveには、記録されているどちらのコンテキストも指定できます。一覧にないソースはMessageKeyの制約を満たしません。

生成された項目がない場合、LingoMessagesは空で、MessageKeyには任意の文字列を指定できます。項目が追加されると、MessageKeyはその文字列キーのユニオン型になります。実行時の動作は変わりません。これらの制約は、編集中のl.textとl.richに適用されます。

ソースに合わせて型を最新に保つ #

テキスト、コンテキスト、プレースホルダーを変更したら、再抽出してください。削除されたメッセージは孤立した項目となり、生成対象から除外されます。コンテキストのない項目からは、同じソースを持つ別の有効な項目にコンテキストがない限り、シグネチャは生成されません。同じソースに複数のコンテキストがある場合は、それらのユニオン型になります。

ファイルに書き込まずに最新の状態か確認するには、次を実行します。

sh
npx lingo extract --src src --source-locale en --check

この処理では、JSONCと宣言の両方を現在の抽出結果と比較します。ローカルでのチェックであり、翻訳リクエストではありません。型チェックと併せて実行し、古い宣言に基づく過去のメッセージ一覧が、気づかないうちに使われ続けるのを防いでください。

値の型と対応範囲 #

ジェネレーターは、最上位のICU引数を認識します。複数形、序数、数値の引数にはnumber、選択の引数にはstring、日付・時刻の引数にはDate | number、単純なプレースホルダーにはstring | numberを使用します。複数形の分岐内に入れ子になったプレースホルダーをすべて検出できるわけではないため、各分岐の値は明示的にテストしてください。

生成されたソースの制約は、textとrichに適用されます。pluralとselectのヘルパーは、それぞれ独自の形式・オプションのシグネチャを維持します。リッチテキストの呼び出しには省略可能なタグマップが追加されますが、宣言では翻訳文のタグ配置までは検証しません。

型チェックでは、呼び出しが抽出されたソースの仕様に適合しているかを確認できます。描画テストでは、読み込んだ翻訳でその値を使用できるかを確認できます。どちらも継続して実施してください。呼び出しが正しくても、対応するカタログ項目が存在しなかったり、翻訳文のICU形式が不正だったりする可能性があります。