Skip to content

JSON ​

対象読者: ロケールごとにネストされたJSONファイル(例: src/i18n/en/translation.json)にコピーをすでに保持しており、そのレイアウトを維持したいプロジェクト。ソースがプレーンテキストで、まだt()がない場合は、代わりにJS/TSアプリにi18nを追加するから始めてください。

CLIは、それらのファイル内の文字列値を走査し、アクティブなLLMプロバイダー上のモデルで翻訳して、json[].outputPathTemplate を使用してロケールごとの出力を書き込みます。translate-docs および translate-svg (cacheDir) と同じSQLiteキャッシュを使用します。

このパイプラインは実行しない extract — カタログstrings.jsonはありません。それを有効にするには、features.translateJsonとトップレベルのjson[]に1つ以上のエントリが必要です。

ロケールごとのモデルオーバーライド ​

translate-json は、ターゲットロケールごとにモデルを解決します。設定されている場合は最初に localeModels(locale)、次に translationModels の順に解決します。これは、zh-Hans / zh-Hant テーマファイルのように、特定のロケールで専用モデルを使用するメリットがあるネストされた JSON バンドルに使用します。AI モデル を参照してください。

ステップ 1: ネストされたJSON向けに初期化 ​

bash
ai-i18n-tools init -t ui-json-bundles -P ollama

そのテンプレートはfeatures.translateJson: trueを設定し、UI抽出とドキュメント翻訳を無効にし、出力をsrc/i18n/{llocale}/translation.jsonとするsrc/i18n/en/translation.jsonを指す単一のjson[]ブロックをスキャフォールドします。また、-Pで渡すプリセット用のprovider / providersブロックも含まれています。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 出力に表示されます。

例(複数のソースファイル、小文字ロケールフォルダー):

json
{
  "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動作
allowlisttranslateKeys に一致するキー(ドットパス、minimatchグロブ)のみ翻訳されます。
denylistskipKeys に一致するキーを除き、すべての文字列値を翻訳します。
both最初に translateKeys を適用し、次に skipKeys からの一致を除外します。

パスにはドット表記(nav.home.label)を使用します。slug のような単独の名前は、任意の深さで最終キーのセグメントに一致します。

ステップ 3: JSONバンドルの翻訳 ​

bash
ai-i18n-tools translate-json

オプションフラグ(translate-docsと同様): ターゲットのサブセットには-l / --locale、ファイルを限定するには-p / --path、--dry-run、--force(一致したファイルのファイルトラッキングとセグメントキャッシュをクリア)、--force-update(ファイルハッシュが一致する場合に再処理。セグメントキャッシュは引き続き適用)、--check-cache(ファイルトラッキングが一致する場合でも、ネイティブスクリプトが強制されるロケールのキャッシュ済みセグメントを再検証)、-b / --batch-concurrency、--prompt-format(xml | json-array | json-object)。

JSONのみのプロジェクトは以下を実行できます:

bash
ai-i18n-tools sync --no-ui --no-svg --no-docs

UIまたはドキュメントも有効になっている場合、sync は translate-docsの後にtranslate-json を実行します(--no-json の場合を除く)。--no-json でJSONをスキップできます。

ファイルおよびロケールごとのカバレッジを確認してください:

bash
ai-i18n-tools status

translateJson がオンの場合、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
i18next ネームスペースファイル(public/locales/en/common.json、{{name}} トークン、key_one / key_other サフィックス)JSON — json[] + translate-json(i18next ネームスペースファイル を参照)
Intlayer *.content.ts 辞書 + useIntlayer (Intlayerからの移行)Intlayerからの移行 — migrate-intlayer、次にUI文字列
Intlayer *.content.ts 辞書 (Intlayerを維持し、翻訳を埋める)Intlayerをその場で翻訳する — translate-intlayer
<text> / <title> / <desc> を含む図解された .svg ファイルfeatures.translateSVG + svg + translate-svg (オプション; 3 つの主要パイプラインのいずれでもありません)

フィールドリファレンス: 設定リファレンスのjson。クリーンアップのキャッシュキーはfile_trackingでjson-block:{blockIndex}:{projectRelPath}を使用します。

i18next ネームスペースファイル ​

JSONパイプラインは、一般的なi18nextのキー/値形式のロケールファイルに対応しています。これには、ネストされたオブジェクト、文字列配列、値における{{name}}補間、および独立した複数形の接尾辞キー (welcome_one、welcome_other) が含まれます。t("some.key")の呼び出し箇所は書き換えません。これらはキーベースのまま維持されます。プロジェクトをai-i18n-toolsのソース文字列t()スキーマに移行するには、呼び出し箇所をt("source text")に変更してください。テキストはsourceLocaleで記述され、どの言語でも使用できます。ソースがIntlayer .content.tsの場合は、migrate-intlayerを実行してください。Intlayerをそのまま使用し、その辞書のみを翻訳するには、translate-intlayerを使用してください。

例(public/locales/en/ 配下のソース英語ネームスペース):

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr", "pt-BR"],
  "features": { "translateJson": true },
  "json": [
    {
      "description": "i18next namespaces",
      "contentPaths": ["public/locales/en/*.json"],
      "outputPathTemplate": "public/locales/{locale}/{basename}"
    }
  ]
}

key_one / key_other / key_zero(およびその他の CLDR サフィックス)は、個別のリーフとして翻訳されます。これにより、i18next はサフィックスによる複数形の解決を引き続き行えます。パイプラインはこれらを単一のカタログ行にまとめ直すことはありません。

MITライセンスの下で公開されています。