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

ドキュメント / ガイド

機械翻訳されたページ

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

言語を追加する

設定ファイルを 1 行変更して翻訳を 1 回実行するだけで、既存の verbatra プロジェクトにターゲットロケールを追加します。既存のロケールには影響しません。

すでにいくつかの言語に翻訳しているプロジェクトに、もう 1 つ言語を追加する場合の手順です。必要なのは設定ファイルの 1 行の変更と 1 回の実行だけです。verbatra は新しいロケールをすべてのキーが欠落した状態として扱い、そこを埋めます。既存のロケールには費用がかかりません。ロックファイルに最新として記録されているためです。

動作するプロジェクトが必要です。設定ファイル、ソースロケールファイル、プロバイダーの API キーを用意してください。まだない場合は、先にクイックスタートを進めます。

設定にロケールを追加する

verbatra.config.ts の targetLocales にコードを追加します。

verbatra.config.ts
import { defineConfig } from "@verbatra/cli";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de", "fr"], 
  format: "i18next-json",
  files: { pattern: "locales/{locale}.json" },
  provider: { id: "gemini", options: { model: "gemini-2.5-flash", maxOutputTokens: 4096 } },
});

ロケールコードのルール

コードは BCP 47 の形式で、ハイフンを使って書きます。pt_BR ではなく pt-BR です。ファイル名にアンダースコアを使っている場合も、設定には pt-BR と書き、files.localeStyle を posix に設定します。verbatra は pt_BR.json というファイル名をそのまま使います。無効なコード、ソースロケール、大文字と小文字だけが異なる 2 つのコードは、設定の読み込み時に拒否されます。詳しいルールはロケールコードを参照してください。新しい言語にプロバイダーが対応しているかどうかは、verbatra doctor で確認できます。

作業量をプレビューする

費用をかける前に、実行で何が起きるかを確認します。

verbatra diff --locales fr

新しいロケールのファイルはまだないため、ソースのすべてのキーが欠落として一覧に出ます。--locales を外すと、ほかのロケールに何も表示されないことを確認できます。diff はプロバイダーを呼び出さず、何も書き込みません。費用の見積もりは verbatra translate --estimate で確認します。詳しくは実行前に費用を見積もるを参照してください。

翻訳する

verbatra translate

実行すると、ソースのすべてのキーを新しいロケールに翻訳し、files.pattern のパス(ここでは locales/fr.json)にファイルを書き込みます。プロバイダーが呼び出されるのは新しいロケールだけです。ほかのロケールには、ロックファイルのベースラインと比べて欠落しているキーも変更されたキーもないため、何も送信されません。

新しいロケールについて何も保持されなかった場合は、ファイルは作成されません。すべてのキーがチェックに失敗した場合、プロバイダーへのリクエストが失敗した場合、トークン予算で保留された場合が該当します。キーは欠落したままで、次回の実行で再試行します。

その後、新しいロケールを含むすべてのロケールが同期していれば、verbatra check は 0 で終了します。

複数形カテゴリが多い言語

言語によっては、ソースより多くの複数形が必要です。英語には one と other がありますが、ポーランド語は 4 つ、アラビア語は 6 つ必要で、フランス語は many が加わります。デフォルトでは、verbatra はソースにある形だけを翻訳し、ほかの形は作りません。実行は成功し、欠落している形を示す PLURAL_CATEGORIES_INCOMPLETE の通知が報告されます。

欠けている形を生成する

i18next JSON と LLM プロバイダーを使っている場合は、欠落している形を verbatra に書かせられます。

verbatra.config.ts
export default defineConfig({
  // ...
  generatePlurals: true,
});

生成された形にも、通常の訳文と同じ整合性チェックが適用されます。

CLDR の複数形

言語に必要な形は、Node.js に組み込まれた CLDR の複数形ルールから決まります。すべての言語が対象で、序数も含みます。ICU 系のフォーマット(next-intl と ARB)は 1 つの値に複数形全体を持つため、生成は不要です。プロバイダーには、ターゲット言語が使う複数形の分岐を過不足なく依頼します。通知にフォールバックする条件は generatePlurals を、言語に必要な形を verbatra がどう判断するかは複数形を参照してください。

ソースだけを保守し続ける

今後編集するのはソースロケールだけです。そこに文字列を追加して translate をもう一度実行すると、verbatra が追加したばかりのロケールを含むすべてのターゲットに反映します。

関連項目

GitHub で編集

このページの内容