設定リファレンス

`sourceLocale`

ソース言語のBCP-47コード（例："en-GB"、"en"、"pt-BR"）。このロケール用の翻訳ファイルは生成されません — キー文字列自体がソーステキストとなります。

実行時i18n設定ファイル（src/i18n.ts / src/i18n.js）からエクスポートされたSOURCE_LOCALEと一致している必要があります。

`targetLocales`

翻訳対象のBCP-47ロケールコードの配列（例：["de", "fr", "es", "pt-BR"]）。

targetLocalesはUI翻訳のための主要なロケールリストであり、ドキュメントブロックのデフォルトロケールリストでもあります。generate-ui-languagesを使用して、sourceLocaleとtargetLocalesからui-languages.jsonマニフェストを構築します。

`uiLanguage`（オプション）

ツール自身のUI言語（CLIヘルプ、ログ/サマリー、および翻訳ダッシュボード）のBCP-47コード。sourceLocale / targetLocalesとは独立しており、-L / --ui-langフラグおよびAI_I18N_LANG環境変数によって上書きされます。不明な値はソースロケール（en-GB）に適切にフォールバックします — 厳密な検証は行われません。ツールUI言語を参照してください。

`languagesManifestPath` (オプション)

ルートレベルのオプション文字列（ui の下にネストされません）。extract と generate-ui-languages が ui-languages.json マニフェストを書き込むパスであり、CLI が表示名と言語リストの後処理のために読み取るパスです。省略した場合、設定の読み込み時に ui.flatOutputDir/ui-languages.json がデフォルトとして使用されます。

以下のときに使用します：

マニフェストは ui.flatOutputDir の外に配置する必要があります（例えば src/i18n/ のアプリヘルパーの隣など）。
言語スイッチャーの後処理（languageListBlock）で、バンドルされたマスターカタログのみではなく、プロジェクトマニフェストからロケールラベルを構築したい場合。

includeUiLanguageEnglishNames はこのファイルを読み取りません — バンドルされたマスターカタログを使用します（下記の ui.uiExtractor を参照）。

レガシー: 設定ファイルの読み込み時にルートレベルの uiLanguagesPath は引き続き受け付けられ、自動的に languagesManifestPath に書き換えられます。

`concurrency`（オプション）

同時に翻訳される最大ターゲットロケール数（translate-ui、translate-docs、translate-svg、およびsync内の対応するステップ）。省略された場合、CLIはUI翻訳に4、ドキュメント翻訳に3を使用します（組み込みのデフォルト）。実行ごとに-j / --concurrencyで上書きできます。

`batchConcurrency`（オプション）

translate-docs、translate-svg、およびtranslate-json（およびsync内の対応するステップ）：ファイルあたりの最大並列LLMbatchリクエスト数（各バッチには多数のセグメントを含めることができます）。省略時のデフォルトは4です。translate-uiには適用されません — 代わりにuiBatchConcurrencyを使用してください。-b / --batch-concurrencyで上書きします。

`uiBatchConcurrency`（オプション）

translate-ui、sync-ui、およびsyncのUIステップ：単一ロケール内での最大並列LLMbatchリクエスト数（50のプレーン文字列チャンク、次に複数形グループ）。省略時のデフォルトは2です。concurrency（並列ターゲットロケール）およびbatchConcurrency（docs/JSON/SVG）とは独立しています。CLIフラグはありません。configで設定するか、プログラマティックなrunTranslateUIにuiBatchConcurrencyを渡してください。

例:

json

{
  "uiBatchConcurrency": 2
}

デフォルトのロケール並列数4の場合、最大8の実行中UI API呼び出しになります。1つの大きなロケールを翻訳する場合はこの値を上げてください（-l de）。プロバイダーがレート制限を設けている場合は低く保ってください。

`fileConcurrency` (オプション)

同一ロケール内で同時に処理されるファイルの最大数 （translate-docs および sync の間）。1 より大きい値に設定すると、同じロケール内のファイルがメモリ使用量を制御するセマフォを使用して並行して処理されます。省略した場合のデフォルトは 1（逐次処理）です。より高い値は、特にすべてのセグメントがすでにキャッシュされている場合（API 呼び出しが不要な場合）、I/O バウンド操作のスループットを大幅に改善できます。

例:

json

{
  "fileConcurrency": 4
}

使用例: キャッシュヒット率100%でsync --force-updateを実行する際に、この値を2-4に設定して総処理時間を短縮します。この改善は、多数の小規模ファイルを処理する場合に特に顕著です。

`batchSize` / `maxBatchChars`（オプション）

translate-docs、translate-svg、およびtranslate-jsonのセグメントバッチ処理：APIリクエストごとのセグメント数と文字数の上限。デフォルト：20セグメント、4096文字（省略した場合）。

`requestTimeout` / `requestTimeoutMs`（任意）

各LLMリクエストの最大待機時間。すべてのプロバイダーに適用されます。requestTimeoutは秒単位、requestTimeoutMsはミリ秒単位です。両方を省略した場合のデフォルトは45秒です。いずれか一方のみを設定してください。プロバイダーがいずれかのフィールドを設定している場合、そのプロバイダーではその値が優先されます。

`provider` と `providers`

provider（トップレベル、オプション）は、providersからアクティブなプロバイダーキーを選択します。プロバイダーが1つだけ設定されている場合はオプションですが、複数設定されている場合は必須です。

providers（トップレベル）は、プロバイダーキーをそのブロックにマッピングします。組み込みキー（以下のプリセットテーブルを参照）にはtranslationModelsのみが必要ですが、その他のキーはカスタムのOpenAI互換エンドポイントを定義し、baseUrl（エンドポイントがキーを必要としない場合を除き、apiKeyEnvも）が必要です。

各providers.<name>ブロックは以下を受け入れます：

translationModels モデルIDの優先順位付きリスト（プレーンなアップストリームID、provider/プレフィックスなし。OpenRouter IDはネイティブのvendor/model形式を保持）。最初のエントリが最初に試行され、後のエントリはエラー時のフォールバックです。これは、より具体的な階層が適用されない場合の、すべてのパイプラインに対するグローバルなデフォルトチェーンです。
uiModels（オプション） translate-ui、複数形生成（ステップ0とパスB）、およびproofread-ui用の、UI専用の順序付きモデルリスト。ターゲットロケールに一致するlocaleModelsエントリの後に、translationModelsの前に試行されます。
localeModels（オプション） すべての翻訳パイプラインに対するロケールごとのオーバーライド。{ "locale": "<BCP-47>", "models": ["…"] }オブジェクトの配列。ロケールタグは、大文字と小文字を区別せずに照合されます（pt-br = pt-BR）。各ロケールのリストは、そのロケールに対してのみ最初に試行され、次にパイプライン固有の階層（UIの場合はuiModels）とtranslationModelsが試行されます。重複する正規化されたロケールキーは、設定の読み込み時に拒否されます。
baseUrl OpenAI互換のベースURL。プリセットのベースURLをオーバーライドします。プリセット以外のプロバイダーには必須です。
apiKeyEnv APIキーを保持する環境変数。プリセットの環境変数をオーバーライドします。
headers このプロバイダーへのすべてのリクエストとともに送信される追加のHTTPヘッダー。
maxTokens リクエストあたりの最大完了トークン数。デフォルト: 8192。
temperature サンプリング温度。デフォルト: 0.2。
requestTimeout このプロバイダーへの各リクエストを待機する最大時間（秒）。トップレベルの requestTimeout / requestTimeoutMs を上書きします。このプロバイダーとトップレベル設定のいずれにもタイムアウトが設定されていない場合、デフォルトは 45 秒です。同じオブジェクトには requestTimeout と requestTimeoutMs のいずれか一方のみを設定してください。
requestTimeoutMs このプロバイダーへの各リクエストを待機する最大時間（ミリ秒）。トップレベルの requestTimeout / requestTimeoutMs を上書きします。このプロバイダーとトップレベル設定のいずれにもタイムアウトが設定されていない場合、デフォルトは 45000（45秒）です。同じオブジェクトには requestTimeout と requestTimeoutMs のいずれか一方のみを設定してください。
pricing（オプション）プロバイダー全体の100万トークンあたりの米ドル：{ "inputPerMTokens": 0.15, "outputPerMTokens": 0.6 }。課金対象の呼び出しにプロバイダーが報告する usage.cost がない場合（OpenRouter以外のほとんどのプロバイダー）、このレートがその呼び出しの入力トークンと出力トークンに適用されます。この金額は翻訳サマリーに含まれ、api_calls 行に保存されます。一致する modelPricing エントリがある場合、このデフォルト値が上書きされます。プロバイダーが報告したコストが置き換えられることはありません。コストなしで保存された行も、後から usage と使用量とコストによって推定できます。
modelPricing（オプション）モデルごとの100万トークンあたりの米ドル：{ "<model-id>": { "inputPerMTokens": 2.5, "outputPerMTokens": 10 } }。そのモデルIDの pricing を上書きします。プロバイダーが usage.cost を省略した場合に呼び出し時に適用され、呼び出しとともに保存されます。

組み込みプロバイダープリセット（キー — ベースURL — APIキー環境変数）：

プロバイダー	ベースURL	APIキー環境変数
`openrouter`	`https://openrouter.ai/api/v1`	`OPENROUTER_API_KEY`
`openai`	`https://api.openai.com/v1`	`OPENAI_API_KEY`
`anthropic`	`https://api.anthropic.com/v1`	`ANTHROPIC_API_KEY`
`gemini`	`https://generativelanguage.googleapis.com/v1beta/openai`	`GOOGLE_API_KEY`
`deepseek`	`https://api.deepseek.com`	`DEEPSEEK_API_KEY`
`cerebras`	`https://api.cerebras.ai/v1`	`CEREBRAS_API_KEY`
`groq`	`https://api.groq.com/openai/v1`	`GROQ_API_KEY`
`mistral`	`https://api.mistral.ai/v1`	`MISTRAL_API_KEY`
`xai`	`https://api.x.ai/v1`	`XAI_API_KEY`
`nvidia`	`https://integrate.api.nvidia.com/v1`	`NVIDIA_API_KEY`
`alibaba`	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`	`ALIBABA_API_KEY`
`apifun`	`https://api.apikey.fun/v1`	`APIFUN_API_KEY`
`ollama`	`http://localhost:11434/v1`	（なし）

従来のトップレベルopenrouterブロック（baseUrl、translationModels、defaultModel、fallbackModel、maxTokens、temperature、requestTimeout、requestTimeoutMsを含む）は引き続き受け付けられ、ロード時にproviders.openrouter（provider: "openrouter"を含む）へ自動マイグレーションされます。defaultModel / fallbackModelはtranslationModelsに統合されます。

1つの設定で複数のプロバイダーを構成し、-Pで切り替える実行可能な例については、examples/multi-providerを参照してください（openai、anthropic、openrouter、deepseekは同じドキュメント上にあります）。

複数のモデルを使用する理由： プロバイダーおよびモデルによってコストが異なり、言語やロケールごとに品質レベルが異なります。translationModelsを単一のモデルではなく、順序付きフォールバックチェーンとして設定することで、リクエストが失敗した場合にCLIが次のモデルを試行できるようにします。

以下のリストは、拡張可能なベースラインとして扱ってください。特定のロケールの翻訳が不十分または失敗した場合は、その言語またはスクリプトを効果的にサポートするモデルを調査し（オンラインリソースまたはプロバイダーのドキュメントを参照）、それらのモデルIDを代替として追加してください。

これらのモデルIDは、-P openrouter（デフォルト）の場合、ai-i18n-tools init [-P <provider>]と一致します。その他のプリセットはinit -P <provider>からネイティブなモデルIDを取得します — 組み込みプロバイダーを参照してください。

このリストは、36の対象ロケールを持つ大規模なドキュメンテーションプロジェクトで広範なロケール対応のテストが行われました。実用的なデフォルトとして機能しますが、すべてのロケールで良好に動作する保証はありません。

translationModelsの例（ai-i18n-tools init [-P <provider>]と同じデフォルト）:

デフォルトのtranslationModelsフォールバックリスト

json

"translationModels": [
  "google/gemini-2.5-flash",
  "meta-llama/llama-3.3-70b-instruct",
  "openai/gpt-4o-mini",
  "google/gemma-4-26b-a4b-it",
  "~anthropic/claude-haiku-latest",
  "z-ai/glm-5.2",
  "google/gemini-3.5-flash",
  "~anthropic/claude-sonnet-latest"
  // … add more fallback models as needed
]

推奨される uiModels: UI文字列は短いですが非常に目立ちます。プレミアムモデルを使用すると、トーン、複数形、一貫性が向上することがよくあります。オプションの uiModels は、一致する localeModels エントリの後、かつ translationModels の前に試行されます（上記のフィールドリストを参照）。例:

UI翻訳に推奨されるuiModels

json

"uiModels": [
  "~anthropic/claude-sonnet-latest",
  "z-ai/glm-5.2"
]

アジア言語に推奨される localeModels: 日本語、韓国語、中国語のロケールは、これらのスクリプトにチューニングされたモデルを使用すると効果的であることがよくあります。ターゲットロケールが一致する場合に 最初に （uiModels / translationModels の前に）試行されるロケールごとのオーバーライドを追加します:

ja, ko, zh-Hans, zh-Hantに推奨されるlocaleModels

json

"localeModels": [
  { "locale": "ja",      "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "ko",      "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "zh-Hans", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "zh-Hant", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] }
]

アクティブなプロバイダーのAPIキー環境変数（プリセットテーブルを参照）を、環境または.envファイルに設定してください。

モデルリストを変更する前に、ai-i18n-tools check-modelsを実行してください。各プロバイダーについて、設定されたすべてのモデルID（translationModels、uiModels、およびすべてのlocaleModelsエントリ）をそのプロバイダーのライブモデルリスト（GET /models）と照合して検証し、欠落しているまたはexpiration_dateを過ぎたIDを報告し、有効なモデルをリスト表示し、無効なIDが1つでもあれば非ゼロで終了します。プロバイダーが価格情報を返す場合（例: OpenRouter）、推定入力/出力価格（100万トークンあたりのUSD）も表示されます。

設定したモデルを実際の翻訳作業で比較するには、ai-i18n-tools bench-modelsを実行してください。translationModels、uiModels、およびlocaleModelsのすべての一意なモデルIDについて、それぞれを個別に（並列で、concurrencyで制限）1つのサンプルを翻訳してベンチマークし、モデルごとの入力/出力トークン数、経過時間、USDコストを出力します。これにより、モデルリストを確定する前に速度と価格のバランスを検討できます。

`features`

フィールド	パイプライン	説明
`translateUIStrings`	1	`t("…")` / `i18n.t("…")` を `strings.json` に抽出し、エントリを翻訳してロケールごとのフラット JSON を書き込みます（抽出は自動的に実行されます。カタログのみを更新するには、スタンドアロンの `extract` を使用します）。
`translateDocs`	2	`.md` / `.mdx` / `.astro` ページを翻訳します。`docs[].docusaurusCatalogDir` が設定されている場合は Docusaurus シェル JSON を翻訳します。Nextra `_meta` / 設定されている場合は辞書を翻訳します。`docsOutput.vitepressThemeCatalog` が設定されている場合は VitePress テーマを翻訳します。`meta.json` / UI カタログは `docsOutput.style` が `"fumadocs"` の場合に翻訳します。
`translateJson`	3	`json[]` 配下の任意のネストされた JSON（`translate-json`）。
`translateSVG`	—	`.svg` ファイルを翻訳（トップレベルの `svg` ブロックが必要です）。

features.translateSVG が true かつトップレベルの svg ブロックが設定されている場合、translate-svg で SVG ファイルを翻訳します。sync コマンドは、両方が設定されている場合にそのステップを実行します（--no-svg でない限り）。

`ui`

sourceRoots
t("…")呼び出しのためにスキャンされるディレクトリまたはグロブパターン（現在の作業ディレクトリからの相対パス）。src/や["src/**/*.ts"]のようなパターンをサポートします。
stringsJson
マスターカタログファイルへのパス。extractによって更新されます。
flatOutputDir
ロケールごとのJSONファイル（de.jsonなど）が書き込まれるディレクトリ。
uiExtractor.funcNames（またはレガシーreactExtractor.funcNames）
スキャンする追加の関数名（デフォルト: ["t", "i18n.t"]）。
uiExtractor.extensions（またはレガシーreactExtractor.extensions）
含めるファイル拡張子（デフォルト: [".js", ".jsx", ".ts", ".tsx"]）。Astroのフロントマターとテンプレート式には.astroを追加します。
uiExtractor.includePackageDescription（またはレガシーreactExtractor.includePackageDescription）
true（デフォルト）の場合、extractは、存在する場合にpackage.json descriptionもUI文字列として含めます。
uiExtractor.packageJsonPath（またはレガシーreactExtractor.packageJsonPath）
オプションの説明抽出に使用されるpackage.jsonファイルへのカスタムパス。
uiExtractor.includeUiLanguageEnglishNames（またはレガシーreactExtractor.includeUiLanguageEnglishNames）

true（デフォルト false）の場合、extract はバンドルされた ui-languages マスターカタログ（sourceLocale + targetLocales から構築）の各 englishName を、ソーススキャンから既に存在しない場合（同じハッシュキー）、strings.json に追加します。languagesManifestPath は読み取りません。

`cacheDir`

cacheDir SQLiteキャッシュディレクトリ（すべてのdocsブロックで共有）。デフォルトは.translation-cache。実行間で再利用します。カスタムのドキュメント翻訳キャッシュから移行する場合は、それをアーカイブまたは削除してください。cacheDirは独自のSQLiteデータベースを作成し、他のスキーマとは互換性がありません。

Git 除外のベストプラクティス:

一時的なキャッシュアーティファクトをコミットしないように、翻訳キャッシュフォルダーの内容を除外します（例: .gitignore または .git/info/exclude を使用）。
cache.db を保持します（定期的に削除しないでください）。SQLite キャッシュを保持することで、変更されていないセグメントの再翻訳を防ぎます。これにより、ai-i18n-tools を使用するソフトウェアの更新や修正時に、ランタイムと API コストの両方を節約できます。
バックアップやデバッグ関連のファイルをコミットしないように、一時ファイルとログファイルを除外します。

例:

gitignore

# Translation cache directory
.translation-cache/*

# Keep SQLite cache for reuse
!.translation-cache/cache.db

# Temporary and log files
*.tmp
*.log

`docs`

ドキュメントパイプラインブロックの配列。translate-docsとsyncのドキュメントフェーズは、各ブロックを順番に処理します。レガシーキーはロード時に引き続き受け入れられ、設定ファイルが書き込み可能であれば書き換えられます。新しい設定では現在の名前を優先してください。

レガシーキー	現在のキー / 動作
`documentations`	`docs`
`markdownOutput`	`docs[].docsOutput`
`jsonSource`	`docs[].docusaurusCatalogDir`
トップレベルの`openrouter`	`providers.openrouter` + `provider: "openrouter"`
`features.translateMarkdown`	`features.translateDocs`
`features.translateJSON`	削除済み（`docs[].docusaurusCatalogDir`または`json[]`を使用）
`features.extractUIStrings`	削除済み（`extract`はUI翻訳の前に実行されます）
`glossary.uiGlossaryFromStringsJson`	`glossary.uiGlossary`
`ui.reactExtractor`	`ui.uiExtractor`（エイリアスは引き続き受け入れられます）
`svg.svgExtractor.forceLowercase`	`svg.forceLowercase`

コンテンツソース

description このブロックの任意の読み取り可能なメモ（翻訳では使用されません）。設定されている場合、translate-docs 🌐 ヘッドラインの先頭に付加され、status セクションヘッダーにも表示されます。
contentPaths 翻訳対象の Markdown/MDX ページ本文および .astro テンプレート（translate-docs が .md、.mdx、.astro をスキャンします）。ディレクトリパスまたはワイルドカードパターン（例："docs/**/*.md"、"guides/*.mdx"、"src/pages/index.astro"）をサポートします。ローカライズされたドキュメントの本文はここから取得されます。
sourceFiles 読み込み時に contentPaths にマージされる任意のエイリアス。
targetLocales このブロックにのみ適用される任意のロケールのサブセット（指定しない場合はルートの targetLocales を使用）。有効なドキュメントロケールは、すべてのブロックの和集合となります。
docusaurusCatalogDir オプション。このブロックの Docusaurus JSON ラベルカタログのソースディレクトリ（例: docusaurus write-translations からの "i18n/en"）。ページ本文は常に contentPaths から取得されます。docusaurusCatalogDir はシェル/UI JSON のみを提供し、MDX は提供しません。
nextraMetaGlob オプション。docsRoot 配下の Nextra _meta.ts / _meta.tsx / _meta.js のグロブ。docsOutput.style が "nextra" で、これが省略されている場合、docsRoot 配下のすべての _meta ファイルが自動的に収集されます。
nextraMetaTranslatableKeys オプション。Nextra _meta オブジェクトで文字列値が翻訳されるプロパティ名（デフォルト: title、display、breadcrumb）。
nextraDictionaryPath オプション。英語の Nextra テーマ辞書モジュール（例: "app/_dictionaries/en.ts"）。translate-docs 中に {dir}/{locale}.ts に翻訳されます。
nextraDictionaryOutputTemplate オプション。ロケール辞書モジュールの出力テンプレート（デフォルト: 辞書ディレクトリに対する {dir}/{locale}.ts）。

出力レイアウト

outputDir このブロックの翻訳済み出力のルートディレクトリ。
docsOutput.style"nested"（デフォルト）、"flat"、"doc-system"、またはエイリアス "docusaurus" / "astro-starlight" / "vitepress" / "nextra"。
docsOutput.localeSubpath{locale}/ と {relativeToDocsRoot} の間の doc-system のパスセグメント（style: "doc-system" を直接使用する場合は必須。エイリアスを使用する場合はプリセット）。Starlight スタイルのロケールフォルダには "" を使用します。
docsOutput.docsRoot Docusaurus レイアウトのソースドキュメントルート（例: "docs"）。省略した場合のデフォルトは "docs"。
docsOutput.pathTemplate カスタムMarkdown出力パス。プレースホルダー："{outputDir}"、"{locale}"、"{LOCALE}"、"{llocale}"、"{relPath}"、"{stem}"、"{basename}"、"{extension}"、"{docsRoot}"、"{relativeToDocsRoot}"。
docsOutput.jsonPathTemplate ラベルファイルのカスタムJSON出力パス。pathTemplateと同じプレースホルダーをサポートします。
docsOutput.localePathLowercasetrueの場合、組み込みの出力レイアウト（nested、flat、doc-system（pathTemplateなし））は、パスに小文字のロケールセグメントを使用します。デフォルトはfalse。astro-starlightとdoc-systemは、空のlocaleSubpathの場合、設定ロード時にデフォルトでtrueになります。
docsOutput.flatPreserveRelativeDirdocsOutput.style = "flat"の場合、ソースサブディレクトリを保持して、同じベース名のファイルが衝突しないようにします。デフォルトはfalse。
docsOutput.rewriteRelativeLinks 翻訳後に相対リンクを書き換えます（docsOutput.style = "flat"で、カスタムのpathTemplateがない場合に自動的に有効になります）。
docsOutput.linkRewriteDocsRoot フラットリンクの書き換えプレフィックスを計算する際に使用されるリポジトリルート。翻訳されたドキュメントが別のプロジェクトルートに存在しない限り、通常は"."のままにしておきます。
docsOutput.rewriteVitepressLinkstrueの場合、翻訳後にVitePressリンクノーマライザーを実行します。docsOutput.styleが"vitepress"の場合、デフォルトで有効になります。docsRootの下でロケールフォルダが英語フォルダと並んで配置されているdoc-systemレイアウトで使用します。READMEスタイルのdocs/guide/…パスをサイトルート（/guide/…）およびロケール相対の../guide/…リンクに書き換えます。VitePressツリーの外にあるリポジトリファイル（LICENSE、examples/）へのリンクには、英語ソースで完全なURLを使用してください。VitePressの統合 — ドキュメントのホームページとしてのREADMEを参照してください。
docsOutput.rewriteNextraLinkstrueの場合、翻訳後にNextraリンクノーマライザーを実行します。docsOutput.styleが"nextra"の場合、デフォルトで有効になります。Next.js i18n用に、content/en/…および相対.mdxパスをロケール非依存のサイトルート（/guide/…）に書き換えます。Nextraの統合 — リンクの規則を参照してください。
docsOutput.fumadocsParser"dot"（デフォルト）または"dir"。dotは英語ソースの隣にstem.{locale}.mdxを書き込みます。dirはNextraのようにロケールフォルダを書き込みます。Fumadocsの統合 — ページレイアウトを参照してください。
docsOutput.rewriteFumadocsLinkstrueの場合、翻訳後にFumadocsリンクノーマライザーを実行します。docsOutput.styleが"fumadocs"の場合、デフォルトで有効になります。コンテンツパスと相対.mdxリンクを/docs/…ルートに書き換えます。
docsOutput.fumadocsUiCatalog オプション。translate-docs内のFumadocs UIオーバーライドカタログのブートストラップと翻訳。フィールド: sourcePath（例: lib/layout.shared.ts）、catalogPath（生成された英語のJSON）、オプションのoutputPathTemplate（デフォルト: catalogPathの隣のui.{locale}.json）。
docs[].fumadocsMetaGlobdocsOutput.styleが"fumadocs"の場合のmeta.jsonコレクションのオプションのglob。デフォルト: docsOutput.docsRootの下の再帰的なmeta.json。
docs[].fumadocsMetaTranslatableKeys Fumadocs meta.json で文字列値が翻訳されるプロパティ名 (デフォルト: title、description)。
docsOutput.vitepressThemeCatalog オプション。VitePress テーマ/ナビゲーション/サイドバーカタログのブートストラップ + translate-docs 内の翻訳。フィールド: configPath (テーマ文字列を含む VitePress 設定)、catalogPath (生成された英語のネストされた JSON)、オプションの outputPathTemplate (デフォルト: theme.{locale}.json の横の catalogPath)。

ポストプロセス

docsOutput.postProcessing 翻訳されたmarkdown本文に対するオプションの変換（YAMLキーおよび非プローゼのフロントマター値は保持されます）。セグメントの再構成とリンクの書き換え（フラットまたはVitePress）の後、addFrontmatter の前に実行されます。
docsOutput.postProcessing.regexAdjustments{ "description"?, "search", "replace" } の順序付きリスト。search は正規表現パターンです（プレーン文字列の場合はフラグ g、または /pattern/flags を使用）。replace は ${translatedLocale}、${sourceLocale}、${sourceFullPath}、${translatedFullPath}、${sourceFilename}、${translatedFilename}、${sourceBasedir}、${translatedBasedir} などのプレースホルダーをサポートします。
docsOutput.postProcessing.languageListBlock{ "start", "end", "separator", "label"? } — ソースおよび翻訳済みmarkdown内の制限付き「他の言語で読む」リンク行を再生成します。label: "local" の場合、エンドニムラベルのために languagesManifestPath（または ui.flatOutputDir/ui-languages.json のマニフェスト）が必要です。

動作とメタデータ

translateFrontmatterFieldsdocsOutputと同じレベル（docs[]ブロックごと）。デフォルトのtrue：Starlight/Docusaurus（title、description、sidebar.label、sidebar_label、keywords、hero.title、hero.tagline、hero.image.alt、hero.actions[].text、pagination_label、prev/nextラベル）のユーザー向けYAML散文を翻訳します。フロントマターブロック全体を変更しないようにするには、falseを設定します。特定のドットパスに制限するには、文字列配列を渡します。
segmentSplittingdocsOutputと同じレベル（docs[]ブロックごと）。translate-docs抽出のためのオプションのよりきめ細かいセグメント：{ "enabled", "maxCharsPerSegment"?, "splitPipeTables"?, "splitDenseParagraphs"?, "maxLinesPerParagraphChunk"?, "splitLongLists"?, "maxListItemsPerChunk"?, "qualityRetrySplit"?, "maxQualityRetrySplitDepth"? }。enabledがtrue（segmentSplittingが省略された場合のデフォルト）の場合、密な段落、GFMパイプテーブル（最初のチャンクにはヘッダー、セパレーター、最初のデータ行が含まれます）、および長いリストは分割されます。サブパーツは単一の改行（tightJoinPrevious）で再結合されます。空白行で区切られたボディブロックごとに1つのセグメントのみを使用するには、"enabled": falseを設定します。qualityRetrySplitがtrue（デフォルト）の場合、すべてのモデルが使い果たされた後にAST検証に失敗したマークダウンセグメントは、段階的に分割され、最初のモデルから再試行されます。maxQualityRetrySplitDepth（デフォルトは3）は再帰的な分割を制限します。
warnMarkdownSourceIssuestrue（省略された場合のデフォルト）の場合、各translate-docs実行は、危険な区切り文字/閉じられていないインラインコードについてマークダウンセグメントを再スキャンし、端末警告を出力し、そのファイルのキャッシュファイルパスのmarkdown_source_issues行を置き換えます。このブロックの警告とSQLite更新をスキップするには、falseを設定します。
addFrontmattertrue（省略された場合のデフォルト）の場合、翻訳されたマークダウンファイルにはYAMLキーが含まれます：translation_last_updated、source_file_mtime、source_file_hash、translation_language、source_file_path、および少なくとも1つのセグメントにモデルメタデータがある場合はtranslation_models（アクティブなプロバイダーからのモデルIDのソート済みリスト）。スキップするにはfalseに設定します。
emphasisPlaceholdersdocs[]ブロックごと。trueの場合、翻訳前にマークダウンの強調区切り文字をプレースホルダーとしてマスクします。CJKロケール（zh、ja、ko）およびrtlLocalesにリストされているロケールではtrueがデフォルトです。それ以外の場合はfalseがデフォルトです。CLI --emphasis-placeholders / --no-emphasis-placeholdersで上書き可能です。
rtlLocales 強調プレースホルダーのデフォルトとしてRTLとして扱われるBCP-47コードのオプションの配列（組み込みのRTL検出とマージされます）。

protectAttributes 省略可能。値が引用符で囲まれた文字列となる追加のJSX/HTML属性名で、翻訳に送信しないもの。組み込みの既定値（class、id、style、src、href、type、data-*、ほとんどのaria-*など）とマージされる。大文字小文字を区別しない。対象は以下のとおり。
.astro パースして置換する抽出（静的HTMLタグおよびattr=内の{expression}ブロックの文字列リテラル）。
- markdown/Astroセグメントの翻訳中にMDXプレースホルダーを抽出（大文字で始まるJSXタグのlabel、tooltip、aria-label、および該当する場合はTabItem value）。

例："protectAttributes": ["variant", "size"]により、variant="primary"内の{items.map(...)}がすべてのロケールで変更されないまま保持される。

翻訳対象となる属性（たとえば"title"や"aria-label"）を、英語からそのままコピーしたい場合にもリストに含めることができます。

protectKeys 省略可能。テンプレートの {expression} ブロックおよびMDXオブジェクトリテラル内（たとえば label: 内の <Tabs values={[ … ]}>）で、引用符で囲まれた文字列値を翻訳しない必要がある追加の オブジェクトプロパティ名。組み込みの既定値（class、key、id、href、src など）とマージされる。大文字小文字は区別しない。

例："protectKeys": ["slug", "code"]により{ slug: 'getting-started', title: 'Getting started' }がスキップされる→slugが保護されている場合、titleのみが翻訳される。

例（docsOutput.style = "flat" — スクリーンショットパス＋オプションの言語リストラッパー）：

フラットレイアウトのpostProcessing例（スクリーンショット＋languageListBlock）

json

"docsOutput": {
  "style": "flat",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders",
        "search": "images/screenshots/[^/]+/",
        "replace": "images/screenshots/${translatedLocale}/"
      }
    ],
    "languageListBlock": {
      "start": "<small id=\"lang-list\">",
      "end": "</small>",
      "separator": " · ",
      "label": "local"
    }
  }
}

`json`

ネストされた JSON 翻訳パイプラインのトップレベル配列。features.translateJson が true の場合（translate-json または sync の JSON ステージ）にのみ使用されます。JSON を参照してください。

フィールド	説明
`description`	CLI / `status`用のオプションの注釈（翻訳対象外）。
`contentPaths`	プロジェクトルート配下のソース`.json`ファイル、ディレクトリ、またはグロブ。一般的なi18next名前空間ファイル（`public/locales/en/*.json`）がサポートされています: ネストされたオブジェクト、配列、文字列値内の`{{var}}`補間、および独立した複数形サフィックスキー（`key_one`、`key_other`）。
`outputPathTemplate`	各ターゲットロケールごとの必須出力パス。プレースホルダー：`{locale}`、`{LOCALE}`、`{llocale}`、`{stem}`、`{basename}`、`{extension}`、`{relativeToSourceRoot}`。
`targetLocales`	このブロック用のオプションのサブセット。指定しない場合、ルートの`targetLocales`を使用。
`keyPolicy.mode`	`allowlist`、`denylist`、または`both`。
`keyPolicy.translateKeys`	モードが`allowlist`または`both`の場合に含めるドットパス／グロブ。
`keyPolicy.skipKeys`	除外するドットパス／グロブ（デフォルトの拒否リストには`id`、`slug`、`href`、`url`、`key`、`code`が含まれます）。

`svg`

SVGファイルのトップレベルのパスとレイアウト。features.translateSVGがtrueの場合（translate-svgまたはsyncのSVGステージ経由）にのみ翻訳が実行される。

フィールド	説明
`sourcePath`	1つ以上のディレクトリまたはグロブパターン（例：`"images/.svg"`、`"/icons/.svg"`）。これらのパターンはプロジェクトルートに対して相対的に解決され、`.svg`ファイルを再帰的にスキャンします。
`outputDir`	翻訳されたSVG出力のルートディレクトリ。
`style`	`pathTemplate` が設定されていない場合のデフォルト値。`"flat"` または `"nested"`。
`pathTemplate`	カスタムSVG出力パス。使用可能なプレースホルダー: `"{outputDir}"`、`"{locale}"`、`"{LOCALE}"`、`"{llocale}"`、`"{relPath}"`、`"{stem}"`、`"{basename}"`、`"{extension}"`、`"{relativeToSourceRoot}"`。
`localePathLowercase`	`true` の場合、組み込みの `flat` / `nested` SVG レイアウトはロケールセグメントを小文字で使用します。カスタムの `pathTemplate` 値は変更されません。小文字のセグメントが必要な場合は `{llocale}` を使用してください。
`forceLowercase`	SVGを再構成する際にテキストを小文字に変換します。すべて小文字のラベルに依存するデザインで有用です。

`glossary`

フィールド	説明
`uiGlossary`	既存の翻訳から自動的に用語集を生成するための `strings.json` へのパス。
`userGlossary`	列`Original language string`（または`en`）、`locale`、`Translation`、任意の`Force`、任意の`Context`を持つCSVへのパス — ソース用語とターゲットロケールごとに1行（`locale`はすべてのターゲットについて`*`にできます）。
`autoAddUserEditedToGlossary`	`true`の場合、UI文字列に対するダッシュボードの編集は、ユーザー用語集に自動的に追加できます。
`contextFiles`	任意のcwd相対Markdownまたはプレーンテキストファイル（`.md`、`.markdown`、`.txt`）。製品や機能の説明を含みます。コマンド開始時にロードされ、UI、ドキュメント、JSON、SVG、および校正プロンプトに注入されます。翻訳対象にも含めたい場合を除き、これらのファイルを`docs[].contentPaths`に配置しないでください。URLは拒否されます。全文が設定されたLLMプロバイダーに送信され、`--debug-failed`ログに表示される可能性があります — 機密情報やPIIを含めないでください。
`contextMaxChars`	モデルに送信される結合済みコンテキストファイルテキストの最大文字数（デフォルト`12000`、ハード上限`100000`）。超過分のテキストは警告とともに切り詰められます。

translate-docsは用語ヒントに同じ用語集を使用しますが、コンパクトなUIラベル略語（Alm.のような末尾ドット形式、またはSize → Tamのような短い単一トークン圧縮）をスキップし、ドキュメントプロンプトが架空の{{…}}トークンへ誘導されないようにします。完全な製品用語および略語化されていないUI翻訳は引き続きヒントとして提供されます。

任意のContext CSV列は、その用語のソース言語での使用ガイダンス（定義、文法的用法、製品上の意味）です。用語が現在のバッチに一致する場合にのみ含まれます。用語のContextノートやcontextFilesの内容を変更すると、次回実行時に該当ロケールのキャッシュされたセグメントとファイル追跡行が無効化され、翻訳が自動的に更新されます。優先するTranslationのみを変更した場合は、--force / --force-updateを渡さない限り既存のキャッシュが使用されます。ダッシュボードでユーザーが編集したキャッシュ行は保持されます。

例:

json

{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md", "i18n/billing-feature.md"],
    "contextMaxChars": 12000
  }
}

空の用語集CSVを生成する：

bash

ai-i18n-tools glossary-generate

リポジトリから contextFiles を作成するには、AIエージェントでコンテキストファイルを生成するのコピー＆ペースト用エージェントプロンプトを使用します。用語行とコンテキストファイルの適用方法については、用語集を参照してください。

翻訳タイプ

UI文字列

ドキュメント

SVG

インテグレーション

画像とスクリーンショット

翻訳ダッシュボード

CLIコマンド

設定リファレンス

`sourceLocale`

`targetLocales`

`uiLanguage`（オプション）

`languagesManifestPath` (オプション)

`concurrency`（オプション）

`batchConcurrency`（オプション）

`uiBatchConcurrency`（オプション）

`fileConcurrency` (オプション)

`batchSize` / `maxBatchChars`（オプション）

`requestTimeout` / `requestTimeoutMs`（任意）

`provider` と `providers`

`features`

`ui`

`cacheDir`

Git 除外のベストプラクティス:

`docs`

`json`

`svg`

`glossary`

UI文字列

ドキュメント

SVG

設定リファレンス ​

sourceLocale ​

targetLocales ​

uiLanguage（オプション） ​

languagesManifestPath (オプション) ​

concurrency（オプション） ​

batchConcurrency（オプション） ​

uiBatchConcurrency（オプション） ​

fileConcurrency (オプション) ​

batchSize / maxBatchChars（オプション） ​

requestTimeout / requestTimeoutMs（任意） ​

provider と providers ​

features ​

ui ​

cacheDir ​

Git 除外のベストプラクティス: ​

docs ​

json ​

svg ​

glossary ​

設定リファレンス

`sourceLocale`

`targetLocales`

`uiLanguage`（オプション）

`languagesManifestPath` (オプション)

`concurrency`（オプション）

`batchConcurrency`（オプション）

`uiBatchConcurrency`（オプション）

`fileConcurrency` (オプション)

`batchSize` / `maxBatchChars`（オプション）

`requestTimeout` / `requestTimeoutMs`（任意）

`provider` と `providers`

`features`

`ui`

`cacheDir`

Git 除外のベストプラクティス:

`docs`

`json`

`svg`

`glossary`