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

ドキュメント / ガイド

機械翻訳されたページ

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

ソースコードからキーを抽出する

コードがすでに呼び出している翻訳キーをソースロケールファイルに集め、テキストを入力して、translate に渡します。

コードがカタログより先に進んでいる場合の手順です。コンポーネントに t("cart.empty", "Your cart is empty") と書いたとき、そのキーを手でコピーせずにソースロケールファイルへ入れられます。国際化したことのないプロジェクトを、空の JSON ファイルではなくコードから始めたい場合にも使えます。

verbatra extract はソースコードを読み、ソースロケールファイルだけを書き込みます。プロバイダーを呼び出さず、API キーは不要で、ネットワークリクエストも送りません。

必要なものは次のとおりです。

  • verbatra の設定ファイル(ない場合は verbatra init を実行します)。
  • i18next の t(...)、$t(...)、i18n.t(...) を呼び出すコード。現在 extract が読み込めるフレームワークはこれだけです。
  • カタログファイル 1 つにつき名前空間 1 つ。t("common:nav.home") のように名前空間付きのキーは、報告されるだけで書き込まれません。1 つの設定が扱うファイルは 1 つだからです。

verbatra にソースコードの場所を指定する

スキャンするディレクトリを指定した extract ブロックを追加します。

verbatra.config.ts
export default defineConfig({
  // ...
  extract: {
    framework: "i18next",
    roots: ["src"], 
  },
});

roots の外側は読み込まれません。node_modules や dist などのビルド出力は常にスキップされます。生成されたコードがルートの下にある場合は、そのディレクトリ名を exclude に追加します。すべてのフィールドは extract を参照してください。

追加される内容をプレビューする

verbatra extract --dry-run

サマリーには、新しいキーとそれを指定したファイルおよび行が一覧で表示されます。何も書き込みません。先に進む前に、次の 3 つの項目を確認します。

  • new keys(新しいキー):実際に実行するとソースファイルに追加されるキーです。
  • dynamic keys(動的キー):キーが 1 つの完全な文字列になっていない呼び出し箇所です。t("user." + id) や t(`nav.${page}`) が該当します。これらは書き込まれません。キーをカタログに手で追加するか、リテラルのキーで呼び出しを書き換えます。
  • conflicts(競合):1 つのキーに対して、2 つの呼び出し箇所で異なるデフォルト値が指定されている場合です。どちらの値も書き込まれないため、テキストを 1 つに決めて呼び出し箇所をそろえます。

キーを追加する

verbatra extract
出力
verbatra extract
  42 files scanned, 18 keys already present
  added 3 keys to locales/en.json
  new keys (3):
    nav.home  src/components/Nav.tsx:14
    nav.away  src/components/Nav.tsx:15
    cart.empty  src/routes/cart.tsx:31
next: verbatra translate (translate the new keys)

呼び出し箇所のデフォルト値が、そのキーのソーステキストになります。カタログにすでにあるキーは値が保たれるため、extract を再実行しても編集内容は上書きされません。新しいキーが見つからなかった実行では、ファイルはバイト単位で同一のままです。

呼び出し箇所にデフォルト値がないキーは、空の値で追加され、--json の結果では withoutDefault に一覧されます。翻訳する前に、ソースロケールファイルにソーステキストを書いておきます。

フォーマットが xliff または apple-xcstrings の場合は、先にソースカタログを作成します(.xcstrings は Xcode で作成します)。extract はそこに追記しますが、作成はしません。

新しいキーを翻訳する

verbatra translate

新しいキーはすべてのターゲットロケールで欠落しているため、実行ではそのキーだけが翻訳されます。バッチが大きい場合は、先に --estimate で費用を見積もります。

TypeScript を使っている場合は、verbatra types でキーの宣言を再生成します。新しいキーのタイプミスがコンパイルエラーになります。

コードとカタログを一致させる

extract はキーを追加するだけです。ほかの方向は、読み取り専用の 2 つのチェックで確認できます。

  • verbatra diff --unused は、どの呼び出し箇所からも参照されなくなったソースキーを一覧します。extract の roots を再利用し、何も削除しません。キーを削除するかどうかは利用者が判断します。一覧をどこまで信頼できるかは使われていないソースキーを参照してください。
  • verbatra doctor --literals は、t(...) を通っていないユーザー向けの文字列を一覧します。JSX のテキストや aria-label が該当します。対象になるものと、除外する方法は未翻訳のリテラルを参照してください。

呼び出し箇所を追加するたびに、verbatra extract を再実行します。繰り返しても安全で、何が見つかっても 0 で終了します。新しいキーがあれば失敗させたい CI のステップでは、終了コードではなく --json の added リストを読みます。

関連項目

GitHub で編集

このページの内容