JSON
UI のコピーをソースの src/i18n/en/translation.json ではなく、ロケールごとにネストされた JSON ファイル (例: t("…")) に保持するプロジェクト向けに設計されています。CLI はこれらのファイル内の文字列値を走査し、アクティブな LLM プロバイダーを介してそれらを翻訳し、json[].outputPathTemplate を使用してロケールごとの出力を書き込みます。translate-docs および translate-svg と同じ SQLite キャッシュ (cacheDir) を使用します。
このパイプラインは実行しない extract — カタログstrings.jsonはありません。それを有効にするには、features.translateJsonとトップレベルのjson[]に1つ以上のエントリが必要です。
ロケールごとのモデルオーバーライド
translate-jsonはモデルをターゲットロケールごとに解決します: localeModels(locale)は最初に構成されたときに、次にtranslationModels。ネストされたJSONバンドルの特定のロケールに専用のモデルが必要な場合にこれを使用します。たとえば、zh-Hans / zh-Hantテーマファイル。詳しくは、プロバイダーとモデルを参照してください。
ステップ 1: ネストされたJSON向けに初期化
ai-i18n-tools init -t ui-json-bundles [-P <provider>]そのテンプレートはfeatures.translateJson: trueを設定し、UI抽出とドキュメント翻訳を無効にし、src/i18n/en/translation.jsonを指し出力がsrc/i18n/{llocale}/translation.jsonとなる単一のjson[]ブロックを作成します。また、デフォルトのprovider / providersブロック（-P <provider>を渡さない限りopenrouter）も含まれています — translate-jsonまたはsyncを実行する前に、対応するAPIキーを設定する（またはローカルのOllamaを使用する）必要があります。プロバイダーとAPIキーを参照してください。リポジトリのレイアウトに合わせてsourceLocale、targetLocales、contentPaths、outputPathTemplateを編集してください。
ステップ 2: json[] の設定
各 json[] ブロックは1つのパイプラインを記述します:
contentPaths— 1つ以上の.jsonファイル、ディレクトリ、またはグロブ（例:"src/i18n/en/translation.json"または"src/i18n/en/overrides/*.json"）。パスはプロジェクトルートから解決されます。outputPathTemplate— 必須。各ターゲットロケールファイルの書き出し先。プレースホルダー:{locale}、{LOCALE}、{llocale}（小文字のロケール。Astroのルートフォルダーに便利）、{stem}、{basename}、{extension}、{relativeToSourceRoot}。targetLocales（オプション）— このブロックのみのサブセット。指定しない場合、ルートのtargetLocalesが適用されます。keyPolicy— どのJSONキーが翻訳対象の文章を保持しているか、安定した識別子かを区別します（以下参照）。description（オプション）— CLIのヘッダーおよびstatus出力に表示されます。
例（複数のソースファイル、小文字ロケールフォルダー）:
{
"sourceLocale": "en",
"targetLocales": ["de", "fr", "pt-BR"],
"features": {
"translateJson": true
},
"cacheDir": ".translation-cache",
"json": [
{
"description": "App UI bundle",
"contentPaths": [
"src/i18n/en/translation.json",
"src/i18n/en/overrides/*.json"
],
"outputPathTemplate": "src/i18n/{llocale}/{basename}",
"keyPolicy": {
"mode": "denylist",
"skipKeys": ["id", "slug", "href", "url", "key", "code"],
"translateKeys": []
}
}
]
}keyPolicy
mode | 動作 |
|---|---|
allowlist | translateKeys に一致するキー（ドットパス、minimatchグロブ）のみ翻訳されます。 |
denylist | skipKeys に一致するキーを除き、すべての文字列値を翻訳します。 |
both | 最初に translateKeys を適用し、次に skipKeys からの一致を除外します。 |
パスにはドット表記（nav.home.label）を使用します。slug のような単独の名前は、任意の深さで最終キーのセグメントに一致します。
ステップ 3: JSONバンドルの翻訳
ai-i18n-tools translate-jsonオプションフラグ（translate-docs と同じ概念）: ターゲットのサブセット用に -l / --locale、ファイルの制限用に -p / --path、--dry-run、--force（一致するファイルのファイル追跡およびセグメントキャッシュをクリア）、--force-update（ファイルハッシュが一致する場合に再処理。セグメントキャッシュは引き続き適用）、-b / --batch-concurrency、--prompt-format（xml | json-array | json-object）。
JSONのみのプロジェクトは以下を実行できます:
ai-i18n-tools sync --no-ui --no-svg --no-docsUIまたはドキュメントも有効になっている場合、sync は translate-docsの後にtranslate-json を実行します（--no-json の場合を除く）。--no-json でJSONをスキップできます。
ファイルおよびロケールごとのカバレッジを確認してください:
ai-i18n-tools statustranslateJson がオンの場合、status は json[] セクションを出力します（✓ 最新、● 古いまたは欠落）。
JSONと他のパイプラインの比較
| 状況 | 使用法 |
|---|---|
JS/TS/Astro の t("…") / i18n.t("…") の UI 文字列 | UI 文字列 — extract + translate-ui |
Docusaurus write-translationsカタログ ({ "key": { "message": "…", "description": "…" } }) | ドキュメント — docs[].docusaurusCatalogDir + translate-docs、json[]は使用しません |
| VitePress テーマ/ナビ/サイドバー文字列 | ドキュメント — docsOutput.vitepressThemeCatalog + translate-docs; json[]を使用しないでください — VitePress インテグレーションを参照 |
Nextra _meta.ts ラベルおよびテーマ辞書 .ts | ドキュメント — translate-docs（style: "nextra"時に_metaを自動、オプションでnextraDictionaryPath）; json[]を使用しないでください — Nextra インテグレーションを参照 |
Fumadocs meta.json ラベルおよび UI オーバーライドカタログ | ドキュメント — translate-docs（style: "fumadocs"時にmeta.jsonを自動、オプションでfumadocsUiCatalog）; json[]を使用しないでください — Fumadocs インテグレーションを参照 |
スタンドアロンのネストされたロケールJSON (ZenBrowserスタイルのtranslation.jsonツリー) | JSON — json[] + translate-json |
<text> / <title> / <desc> を含む図解された .svg ファイル | features.translateSVG + svg + translate-svg (オプション; 3 つの主要パイプラインのいずれでもありません) |
フィールドリファレンス: 設定リファレンスのjson。クリーンアップのキャッシュキーはfile_trackingでjson-block:{blockIndex}:{projectRelPath}を使用します。