ドキュメント / ガイド
機械翻訳されたページ
言語を追加する
設定ファイルを 1 行変更して翻訳を 1 回実行するだけで、既存の verbatra プロジェクトにターゲットロケールを追加します。既存のロケールには影響しません。
すでにいくつかの言語に翻訳しているプロジェクトに、もう 1 つ言語を追加する場合の手順です。必要なのは設定ファイルの 1 行の変更と 1 回の実行だけです。verbatra は新しいロケールをすべてのキーが欠落した状態として扱い、そこを埋めます。既存のロケールには費用がかかりません。ロックファイルに最新として記録されているためです。
動作するプロジェクトが必要です。設定ファイル、ソースロケールファイル、プロバイダーの API キーを用意してください。まだない場合は、先にクイックスタートを進めます。
設定にロケールを追加する
verbatra.config.ts の targetLocales にコードを追加します。
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_ ではなく pt-BR です。ファイル名にアンダースコアを使っている場合も、設定には pt-BR と書き、files.localeStyle を posix に設定します。verbatra は pt_ というファイル名をそのまま使います。無効なコード、ソースロケール、大文字と小文字だけが異なる 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_ の通知が報告されます。
欠けている形を生成する
i18next JSON と LLM プロバイダーを使っている場合は、欠落している形を verbatra に書かせられます。
export default defineConfig({
// ...
generatePlurals: true,
});生成された形にも、通常の訳文と同じ整合性チェックが適用されます。
CLDR の複数形
言語に必要な形は、Node.js に組み込まれた CLDR の複数形ルールから決まります。すべての言語が対象で、序数も含みます。ICU 系のフォーマット(next-intl と ARB)は 1 つの値に複数形全体を持つため、生成は不要です。プロバイダーには、ターゲット言語が使う複数形の分岐を過不足なく依頼します。通知にフォールバックする条件は generatePlurals を、言語に必要な形を verbatra がどう判断するかは複数形を参照してください。
ソースだけを保守し続ける
今後編集するのはソースロケールだけです。そこに文字列を追加して translate をもう一度実行すると、verbatra が追加したばかりのロケールを含むすべてのターゲットに反映します。
関連項目
verbatra translateとverbatra diff:このページで使ったすべてのオプション- 設定ファイル:
targetLocales、files.pattern、files.localeStyle - 言語とロケール:各プロバイダーが対応する言語、文字体系、地域バリアント、右から左に書くテキスト
- ロックファイルと来歴:再実行しても既存のロケールに費用がかからない理由