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

リファレンス / 設定

機械翻訳されたページ

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

設定ファイル

すべての設定キーの型、デフォルト、追加されたバージョンに加え、ファイルの置き場所と、不正な設定がどう失敗するかを説明します。

verbatra は、シークレットを含まない 1 つの設定オブジェクトを読み込み、処理の前に検証します。API キーは設定から読み込まれることがないため(API キーは環境変数から読み込む)、設定ファイルは安全にコミットできます。

最小構成の設定

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

export default defineConfig({
  // Locales and files: required
  sourceLocale: "en",
  targetLocales: ["de", "fr"],
  format: "i18next-json",
  files: {
    // {locale} is the only token
    pattern: "locales/{locale}.json",
  },

  // Provider: required; the API key comes from the environment, never from here
  provider: {
    id: "gemini",
    options: {
      // example model id; use your provider's current one
      model: "gemini-2.5-flash",
      maxOutputTokens: 4096,
    },
  },

  // Optional groups, each off or at its default until you add it:
  // tone: "informal",
  // glossary: "glossary.json",
  // network: { policy: "local-only" },
  // sensitiveData: { mode: "warn" },
  // maxTokens: 200000,
  // budgetBehavior: "stop",
});

各項目の説明は、ロケールとファイル、provider、glossary、network、機密情報ガード、maxTokens と budgetBehavior、rates、extract を参照してください。

defineConfig は引数に型を付けるだけです。options.model はプロバイダーのモデル ID に補完されますが、実行時には空でない文字列ならどれでも受け付けられます。

すべての設定キー

不明なキーは、$schema と、maxLength、rates.table、localeMap、インラインの glossary のようにキー名を自分で付けるマップを除き、どの階層でも拒否されます。そのため、API キーを設定に置くことはできません。

設定キー型デフォルト追加バージョン説明
$schema文字列なし0.9.0エディターに JSON Schema を指定するキー(エディターでの検証を参照)で、実行時には無視される
sourceLocaleロケールコード必須0.1.0ソース文字列を書いているロケール
targetLocalesロケールコードの配列必須0.1.01 つ以上。sourceLocale は含められず、大文字と小文字を無視して同じになる 2 つも含められない
formatフォーマット ID必須0.1.0ロケールファイルのフォーマット、または外部のアダプター用の custom: ID(カスタムフォーマットアダプターを書くを参照)
files.pattern文字列必須0.1.0各ロケールファイルへのパス。{locale} プレースホルダーを含める
files.localeStyle"literal"、"posix"、"android""literal"0.7.0パスの中で {locale} をどう表記するか
provider.idプロバイダー ID必須0.1.0翻訳プロバイダー。機械翻訳を使わない場合は none
provider.optionsオブジェクト必須(none を除く)0.1.0各プロバイダーに固有のオプション
glossaryオブジェクトまたはファイルパスなし0.1.0固定の訳、使用を禁止する訳語、翻訳しない用語
tone"formal"、"informal"、"neutral"、またはマップなし0.1.0翻訳に使うトーン(適用の仕方はプロバイダーごとのトーンと用語集を参照)。マップはターゲットロケールごとにトーンを指定し、残りは default です。新機能
prune真偽値false0.3.0孤立したキーをターゲットファイルとロックファイルから削除する。translate --prune で上書きできる
generatePlurals真偽値false0.3.0ターゲット言語に必要な CLDR の複数形を合成する
fuzzyCache.enabled真偽値ブロック内では必須0.11.0わずかに変更されたソースの訳文を再利用する
fuzzyCache.threshold数値、0.5 から 10.90.11.0古いソースと新しいソースがどれだけ似ている必要があるか
humanEdits"protect"、"suggest"、"overwrite""protect"0.12.0人が書いた古くなったキーを実行がどう扱うか
pinnedKeys文字列の配列なし0.12.0機械による書き込みが一切触れないキーのパターン(* ワイルドカード)
network.policy"any"、"local-only"、"allowlist""any"0.12.0プロバイダーが接続してよいホスト(ネットワークアクセスを制限するを参照)
network.allowedHosts文字列の配列なし。"allowlist" では必須0.12.0追加で許可するホスト:名前、*.suffix ワイルドカード、IP、CIDR 範囲
sensitiveData.mode"off"、"warn"、"block"、"redact"ブロック内では必須。ブロックがない場合は "off"0.12.0送信前の機密情報に対する実行の動作(機密情報ガードを参照)
sensitiveData.detectors検出器 ID の配列secret、email、iban、credit-card0.12.0実行する検出器。phone、ip、private-host は明示的に有効にする必要がある
sensitiveData.patterns文字列の配列なし0.12.0コードネームなど、独自の用語用の正規表現
sensitiveData.allow文字列の配列なし0.12.0報告しない一致。* はワイルドカードで、大文字と小文字は無視される
maxBatchSize正の整数500.3.01 回のプロバイダーリクエストに含めるエントリの最大数
maxLengthキーから正の整数へのマップなし0.11.0キーごとの長さの上限(書記素クラスター単位)
maxTokens正の整数なし0.5.0実行全体のトークン予算
budgetBehavior"warn"、"stop""warn"0.5.0maxTokens に達したときに警告するか、送信を止めるか
rates.asOfYYYY-MM-DD 形式の日付ブロック内では必須0.11.0単価を確認した日付
rates.currency大文字 3 文字ブロック内では必須0.11.0すべての単価の通貨(USD など)
rates.table単価キーから単価へのマップブロック内では必須0.11.0単価キーごとの単価
extract.framework"i18next"ブロック内では必須0.11.0ソーススキャンが探す呼び出し箇所の種類
extract.roots文字列の配列ブロック内では必須0.11.0スキャンするディレクトリ。1 つ以上
extract.exclude文字列の配列なし0.11.0追加でスキップするディレクトリ名
extract.literals.ignore文字列の配列なし0.11.0doctor --literals が除外する正確なテキスト
extract.unused.ignore文字列の配列なし0.11.0diff --unused が報告しないキーまたは * パターン

ロケールとファイル

  • files.pattern は、唯一のプレースホルダーである {locale} を含む必要があります。パスはプロジェクトルートを基準に解決され、locales/{locale}.json は locales/de.json になります。リテラルなパスでありグロブではないため、1 つの設定で扱えるのはロケールごとに 1 ファイルです(名前空間のレイアウト)。apple-xcstrings は、すべてのロケールを 1 つのカタログに解決します(Xcode String Catalogs (.xcstrings))。

  • files.localeStyle は、プレースホルダーの展開結果を決めます。

    • literal は、ほとんどのレイアウトが必要とするとおり、設定したタグをそのまま書きます。
    • posix は、gettext と Java の messages_{locale}.properties で - を _ に置き換えます(pt-BR は pt_BR になります)。de-1996 のようなバリアントには posix 表記がありません。gettext-po は、文字体系を gettext 方式で表記します(次のセクション)。
    • android はリソースディレクトリに展開します。パターンは res/{locale}/strings.xml のように書きます。ソースは values、続いて values-de、values-pt-rBR、values-b+zh+Hans です。

    スタイルが表記できないロケールは拒否されます。

gettext のロケール名

format: "gettext-po" と localeStyle: "posix" では、ファイルに gettext 形式の名前(language_REGION@modifier)が使われます。設定には BCP 47 のコードをそのまま書きます。

設定上のコードファイル名での表記
pt-BRpt_BR
es-419es_419
sr-Latnsr@latin
sr-Latn-RSsr_RS@latin
uz-Cyrluz@cyrillic
ks-Deva-INks_IN@devanagari
zh-Hant-TWzh_TW
sr-Cyrl-RSsr_RS

言語と地域から決まる文字体系は省略されるため、zh-TW と zh-Hant-TW を同時に指定すると LOCALE_PATH_COLLISION で失敗します。gettext の修飾子がない文字体系(たとえば zh-Hant だけ)は LOCALE_LAYOUT_INVALID で失敗します。verbatra init はこれらの名前を読み戻します。ほかのフォーマットは ICU の表記(sr_Latn)のままです。

ロケールコード

すべてのロケールコードは Intl.getCanonicalLocales が受け付けるタグで、言語サブタグは 2 文字または 3 文字でなければなりません。そうでない場合、読み込みは CONFIG_INVALID で失敗します。pt_BR(localeStyle: "posix" では pt-BR と書きます)と german は拒否されます。zh-hant-tw や非推奨の iw のように、有効だが正規形でないコードは、書いたとおりに動作します。

provider

provider.id はプロバイダーのいずれか 1 つを選びます。none の場合は options を省略できますが、書く場合は {} にします(機械翻訳なしで実行する)。ほかのすべてのプロバイダーは options.localeMap と options.requestTimeoutMs を受け付けます(プロバイダーに送られるロケールコード)。バージョン 0.12.0 以上では、localeMap のように provider の下に置き違えたキーは CONFIG_INVALID で失敗します。

glossary

固定の訳で翻訳する用語です。インラインで書くか、同じ形の JSON ファイルへのパスで指定します(マージはされません)。バージョン 1 は、ソース用語ごとに、すべてのロケールに共通の訳を 1 つ対応付けます。

verbatra.config.ts
export default defineConfig({
  // ...
  glossary: {
    "Sign in": "Anmelden",
  },
  // or: glossary: "glossary.json",
});

相対パスは設定ファイルのディレクトリを基準に解決されます。ファイルは UTF-8 で、1 MiB 以下である必要があり、読み込み時に 1 回だけ読み取られます。ファイルがない場合、JSON が不正な場合、形が不正な場合は CONFIG_INVALID で失敗し、パス(バージョン 2 ではフィールドも)が示されます。__proto__ という用語はファイルに書いてください。JavaScript のリテラルではプロトタイプになってしまいます。

ロケールごとの用語集(バージョン 2)

バージョン 2 では、ロケールごとの訳、禁止する訳語、そのまま書く用語を追加できます。

glossary.json
{
  "version": 2,
  "terms": [
    {
      "source": "Dashboard",
      "targets": { "de": "Übersicht", "fr": "Tableau de bord" },
      "forbidden": { "de": ["Instrumententafel"] },
      "note": "The start page after sign-in",
      "partOfSpeech": "noun"
    },
    { "source": "Sign in", "target": "Anmelden", "caseSensitive": true }
  ],
  "doNotTranslate": ["verbatra", { "term": "Acme", "caseSensitive": false }]
}
フィールド意味
version常に 2。ほかの数値は失敗する
terms[].sourceソース用語。各用語は 1 回だけ現れる
terms[].target自身の targets エントリがないすべてのロケールの訳
terms[].targetsロケールごとの訳。ロケールはまず自身のエントリ、次にベース言語のエントリ(de は de-AT を含む)、最後に target を使う。コードは正規形で、大文字と小文字を無視して比較される
terms[].forbiddenロケールが決して使ってはならない訳語。地域ロケールはベース言語のリストにも従う
terms[].caseSensitive用語、訳、禁止する訳語を大文字と小文字を区別して照合する。デフォルトは false
terms[].note、terms[].partOfSpeech自由記述のコンテキスト。LLM プロバイダーにデータとして送られる
doNotTranslate翻訳せずにそのままコピーする用語。文字列だけの場合は大文字と小文字を保つ。{ "term", "caseSensitive": false } では変わることがある

各用語には target、targets エントリ、forbidden リストのいずれかが必要です。用語は、自身の訳を禁止すること、同じロケールを 2 回挙げること、doNotTranslate にも現れることができません。空のテキストは認められません。長さの上限は、用語が 200 文字、訳または禁止する訳語が 2,000 文字、note が 500 文字、partOfSpeech が 50 文字です。ロケールの翻訳キャッシュのフィンガープリントは、そのロケール自身の用語だけを対象にします。バージョン 1 のファイルはフィンガープリントを保ちます。updateGlossaryTerm は、バージョン 1 では表現できない編集の場合に限り、ファイルをバージョン 2 として書き直します。

Studio でレビューするで編集できるのは、ファイルとして指定した用語集だけです。編集は 1 回に 1 つの用語です。どのプロバイダーが用語集を適用するかはプロバイダーごとのトーンと用語集にあります。すべての出力は、あとで翻訳の安全性のチェックを通ります。

generatePlurals

true の場合、verbatra は、ターゲットに必要でソースにない CLDR の複数形(ポーランド語の few と many など)を合成します。序数キー(<key>_ordinal_<category>)も CLDR の序数ルールで合成します。対応するのは、LLM プロバイダーを使う i18next-json だけです。それ以外、および CLDR のルールがないロケールでは、複数形の警告が出ます(序数は other とみなします)。CLI のオプションはありません。SDK の translate() は、実行ごとの上書きを受け付けます。

fuzzyCache

fuzzyCache: { enabled: true } を指定すると、変更されたソースが、以前の形の訳文を再利用できます。条件は、2 つが threshold 以上似ていることです。再利用には常に FUZZY_CACHE_REUSE のフラグが付きます(あいまい一致による再利用)。--no-cache で回避できます。

humanEdits と pinnedKeys

humanEdits が対象とするのは、値を人が書いた古くなったキー(human、import、external の来歴)です(来歴:各値を誰が書いたかを参照)。pinnedKeys に一致するキー(["legal.*", "brand.name"] など)は、humanEdits の設定にかかわらず、機械が書き込むことはありません。* はドットを含む任意の文字列に一致し、大文字と小文字を区別します。各モードの動作は人手翻訳を保護するにあります。

network

ネットワークアクセスを制限するを参照してください。

verbatra.config.ts
network: { policy: "local-only", allowedHosts: ["gpu.lan"] }

maxBatchSize

欠落しているエントリと変更されたエントリは、この大きさ以下の連続したサブバッチで送られます(バッチ処理を参照)。CLI のオプションでは上書きできません。

maxLength

文字列にレイアウト上の制約がある場合の、キーごとの長さの上限です。

verbatra.config.ts
maxLength: {
  "nav.dashboard": 18,
  "cta.submit": 12,
}
  • 設定ファイルまたは verbatra.limits.json: キーはリテラルに一致し、グロブとしては扱いません。どちらにも設定されていないキーは測定されません。setKeyLengthLimit が受け付けるのはソースのキーだけなので、Studio は生成された複数形の上限を設定できません。そのキー自身に手で書いたエントリは適用されます。ロックファイルの隣のファイルは { "version": 1, "maxLength": { ... } } を受け付け、キーごとに設定ファイルが優先され、setKeyLengthLimit がそのファイルに書き込みます。
  • 書記素クラスター:長さは、空白を含む知覚上の文字数で数えます。絵文字、アクセント付きの文字、CJK の文字はそれぞれ 1 です。上限の値そのものは超過に含みません。
  • 対象となる値:translate がそのキーに対して生成するすべての値(キャッシュの再利用を含む)です。最新の状態のキーは、check --qa、check --file、export --include-unchanged が読み込むときだけ対象になります。
  • 警告のみ:超過した値も書き込まれてロックファイルに記録され、レビュー用に MAX_LENGTH_EXCEEDED のフラグが付きます。

maxTokens と budgetBehavior

maxTokens は実行全体の予算です。すべてのプロバイダー呼び出し(翻訳と複数形の生成)とすべてのターゲットロケールにわたる、入力と出力のトークンの合計です。translate --max-tokens は 1 回の実行に限って厳しくできますが、緩めることはできず、常に厳格な "stop" として働きます。

budgetBehavior は、上限に達したときの動作を決めます。

  • "warn"(デフォルト)は、使用量を数えて超過にフラグを付けますが、続行します。
  • "stop" は、maxTokens をすべてのプロバイダーに適用される上限にします。実行は、実行前に費用を見積もる場合と同じ方法で、リクエストごとに事前に費用を予測し、maxTokens を超えるリクエストを拒否します。そのリクエストのキーと、まだ試していないすべてのキー(ロケールの残りと、あとのすべてのロケール。それらの差分と孤立したキーの報告は引き続き実行されます)は保留され、ロックファイルの以前のハッシュを保ち、次回の実行で再試行されます。

"stop" では次のとおりです。

  • 各リクエストのあとで、合計はプロバイダーが報告した使用量に合わせて調整されます。そのため、実行は maxTokens をわずかに超えて終わる場合があります(budget については RunSummary の構造を参照)。機械翻訳プロバイダーはトークンを報告しないため、予測値で予算を管理します。
  • 失敗したリクエストや途中で切れたリクエストは、全額が計上されます。
  • 予測には、機械翻訳プロバイダーでも、LLM プロンプトの固定の余裕分が加算され、バッチ全体が対象になります。そのため、1 バッチの予測より小さい maxTokens は、毎回の実行でそのバッチを拒否します。
  • 保留されたキーがあるロケールは partial になり、キーが 1 つも書き込まれなかった場合は failed になります。どちらも終了コード 1 です。"warn" では終了コードは変わりません。

予算が制限するのは 1 回の translate の実行であり、1 エントリの再翻訳には適用されません。watch は実行ごとに新しい予算で始めます。予算を設定すると、実際の実行では --concurrency を 1 より大きくできません。ドライランは対象外です。

2 つの異なる maxTokens

最上位の maxTokens は、この実行全体の予算です。Anthropic の無関係な provider.options.maxTokens は、1 回のレスポンスの上限です(Anthropic を参照)。

rates

translate --estimate が読み込みます。記録された各実行の履歴の費用を算出するときにも読み込みます。

verbatra.config.ts
rates: {
  asOf: "2026-01-15",
  currency: "USD",
  table: {
    // placeholders: copy the current rates from each provider's pricing page
    "gemini/gemini-2.5-flash": { inputPerMillionTokens: 1, outputPerMillionTokens: 2 },
    deepl: { perMillionCharacters: 1 },
  },
}

table のキーは provider/model で、モデルがないプロバイダー(deepl、google-translate)では ID だけです。エントリはトークン課金(inputPerMillionTokens、outputPerMillionTokens)か文字課金(perMillionCharacters)のどちらかで、両方にはできません。負の単価、100 万あたり 1,000,000,000 を超える単価、単位の誤りは拒否されます。openai-compatible と libretranslate は請求書を発行しないため、単価なしで数量だけが報告されます。

extract

extract、doctor --literals、diff --unused だけが読み込みます。

verbatra.config.ts
extract: {
  framework: "i18next",
  roots: ["src", "app"],
  exclude: ["generated"],
  literals: { ignore: ["Acme Inc."] },
  unused: { ignore: ["emails.*"] },
}
  • framework は、抽出器があるものを指定する必要があります(検出するもの)。それ以外は拒否されます。
  • roots はプロジェクトルートを基準に解決されます。exclude は、ルートの下のどこでも一致するディレクトリ名(パスではありません)を、常にスキップされるディレクトリの集合に追加します(スキャンの範囲を参照)。
  • literals.ignore は、空白を詰め、参照を展開したあとのリテラルのテキスト全体に一致します(未翻訳のリテラル)。
  • unused.ignore は、デコード後のキーに一致します(diff --unused)。

探索順序

verbatra は作業ディレクトリから上方向に探索し、最初に見つかったものを使います。.git を含む最も近いディレクトリで止まり、なければホームディレクトリで止まります(ホームが作業ディレクトリの上にない場合は作業ディレクトリです)。そのため、リポジトリより上にある設定ファイルを拾うことはありません。

  1. package.json("verbatra" プロパティ)
  2. .verbatrarc
  3. .verbatrarc.json
  4. .verbatrarc.yaml
  5. .verbatrarc.yml
  6. .verbatrarc.js
  7. .verbatrarc.cjs
  8. .verbatrarc.ts
  9. verbatra.config.js
  10. verbatra.config.cjs
  11. verbatra.config.ts

--config <path> は、作業ディレクトリからの相対パスで 1 つのファイルだけを読み込みます。SDK での優先順位は loadConfig にあります。

エディターでの検証

@verbatra/sdk は、zod スキーマから生成した JSON Schema を同梱しています。どのインストール(npx、依存関係を巻き上げたモノレポ、リモートのエージェント)でも使えるよう、固定の URL でも公開しています。

https://verbatra.kreitz-webdev.de/schema/v1/config.json

オフラインの場合、またはインストール済みのバージョンに固定する場合は、パッケージ内のコピー ./node_modules/@verbatra/sdk/dist/config-schema.json を使います(スキーマを参照)。

.verbatrarc.json と .verbatrarc は、VS Code 用に $schema キーを受け付けます。

.verbatrarc.json
{
  "$schema": "https://verbatra.kreitz-webdev.de/schema/v1/config.json",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "format": "i18next-json",
  "files": { "pattern": "locales/{locale}.json" },
  "provider": { "id": "gemini", "options": { "model": "gemini-2.5-flash", "maxOutputTokens": 4096 } }
}

拡張子のない .verbatrarc には、ワークスペースのファイルマッチも必要です。

.vscode/settings.json
{
  "json.schemas": [
    {
      "fileMatch": [".verbatrarc", ".verbatrarc.json"],
      "url": "https://verbatra.kreitz-webdev.de/schema/v1/config.json"
    }
  ]
}

YAML の設定ファイルには、YAML Language Server のコメントを書きます。

.verbatrarc.yaml
# yaml-language-server: $schema=https://verbatra.kreitz-webdev.de/schema/v1/config.json
sourceLocale: en
targetLocales: [de, fr]
format: i18next-json
files:
  pattern: "locales/{locale}.json"
provider:
  id: gemini
  options:
    model: gemini-2.5-flash
    maxOutputTokens: 4096

package.json はスキーマを受け付けません。実行可能な形式は defineConfig で型付けされます。

スキーマで検証できないこと

設定の読み込みだけが、次のルールをチェックします。targetLocales のルールとロケールコード、localeMap と tone マップのキー、openai-compatible の baseUrl と apiKeyEnvVar のルール、有効な network.allowedHosts のアドレスと範囲、機密情報ガードの安全ルール内の sensitiveData.patterns、インラインのロケールごとの用語集(バージョン 2)の用語のルールです。

作業ディレクトリと .env

作業ディレクトリ(verbatra を実行する場所、または --cwd)は、設定ファイルの探索の起点で、環境ファイルを置く場所でもあります。ロケールのパス、verbatra.lock.json、キャッシュ、来歴ファイル、.verbatra-local/ は、見つかった設定ファイルのディレクトリであるプロジェクトルートを基準に解決されるため、サブディレクトリから実行しても同じファイルを使います。--config を指定した場合は作業ディレクトリがルートになります。別の場所にある設定ファイルでは、用語集のパスがそのファイル自身のディレクトリを基準に解決されるため、stderr に注記が出ます。--out や check --file のように自分で渡すパスは、作業ディレクトリを基準に解決されます。

読み込みに失敗した場合

  • CONFIG_NOT_FOUND:探索したどの場所にも設定ファイルがないか、--config のパスが存在しません。
  • CONFIG_INVALID:設定ファイルは見つかりましたが、使えません。メッセージには、すべての問題がキーのパスとともに一覧されます。不明なキーの場合は、API キーが環境変数から読み込まれるというヒントが加わります。解析の失敗ではファイル名が示されます(YAML では行と列も)が、内容は引用されません。また、すべてのメッセージは API キーの秘匿化を通ります。

CLI はどちらも 2 で終了します。

GitHub で編集

このページの内容