ai-i18n-tools

Appearance

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向けに初期化 ​

bash
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 出力に表示されます。

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

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 辞書 + useIntlayerIntlayer からの移行 — migrate-intlayer、その後 UI 文字列
<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("English text") に変更します（または、ソースが Intlayer の .content.ts の場合は migrate-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ライセンスの下で公開されています。

Copyright © Waldemar Scudeller Jr.