Astro連携

ai-i18n-toolsをAstroで利用するには、一般的な2つのセットアップがあります。Astro Starlightドキュメントサイトと、プレーンなAstroマーケティングサイトまたはアプリサイトです。どちらもページコンテンツにはDocuments (translate-docs)を使用します。プレーンなAstroサイトでは、フロントマターや共有データ内のt()文字列にUI文字列 (extract / translate-ui)を組み合わせて使用することがよくあります。

UI文字列、ドキュメント、および以下の実行可能な例も参照してください。

Astro Starlight

Astro Starlightドキュメントサイトには、init -t ui-starlightとdocsOutput.style: "astro-starlight"を使用します。このプリセットは、空のlocaleSubpathを持つdoc-systemのエイリアスです。翻訳されたページは、英語のソースツリーの横にあるsrc/content/docs/<locale>/に配置されます。

クイックスタート

ai-i18n-tools init -t ui-starlight [-P <provider>]
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync   # or: ai-i18n-tools sync
pnpm dev             # Starlight dev server (project-specific script)

ページレイアウト

英語のMarkdownとMDXはStarlightのコンテンツルート（通常はsrc/content/docs/）にあります。翻訳されたコピーはソースツリーの横に書き込まれます。

src/content/docs/quick-start.md     →  src/content/docs/de/quick-start.md
src/content/docs/guide/setup.mdx    →  src/content/docs/fr/guide/setup.mdx

docs[] ブロックを1つ設定します：

{
  "contentPaths": ["src/content/docs/"],
  "outputDir": "src/content/docs",
  "docsOutput": {
    "style": "astro-starlight",
    "docsRoot": "src/content/docs"
  }
}

contentPathsを英語の.md / .mdxファイルとディレクトリに指定します。docsRootをStarlightがコンテンツルートとして使用するのと同じフォルダに設定します。

Starlight UIのオーバーライドは、必要に応じて別のdocs[]ブロックでsrc/content/i18n/en.jsonをjsonPathTemplateとともに使用できます。詳細については、ドキュメント — ドキュメントの初期化を参照してください。

Starlightは多くのロケール向けに組み込みのUI文字列（ナビゲーションラベル、検索プレースホルダー、目次など）を提供しています。別のシェル/テーマパイプラインを設定する必要はありません。ページコンテンツにはtranslate-docsのみを使用してください。他のフレームワークについては、フレームワークのシェル翻訳を参照してください。

プロジェクト例

examples/astro-docs — 英語ソースはsrc/content/docs/、コミットされた翻訳はsrc/content/docs/<locale>/、RTLロケール (ar)、および用語集駆動型翻訳。pnpm devをポート3050で実行します。

プレーンなAstro (マーケティングおよびアプリサイト)

静的なAstroマーケティングサイトまたはアプリサイト（Starlightではない）の場合、Astro組み込みのi18nルーティングとai-i18n-toolsを組み合わせます。参照実装はexamples/astro-websiteです。英語は/、ターゲットロケールは/{locale}/です。

ほとんどのチームは、同じページで2つのパイプラインのハイブリッドを使用します。

パイプライン	使用対象	コマンド	出力
ページ HTML	テンプレート本体の見出し、段落、ナビゲーションラベル、インライン配列	translate-docs	ロケールごとに src/pages/{locale}/index.astro
UI 文字列 (t())	フロントマター データ、タブラベル、共有配列	extract → translate-ui	public/locales/{locale}.json (英語ソースをキーとして)

クイックスタート

ai-i18n-tools init -t ui-astro-website [-P <provider>]
# enable features.translateDocs and add a docs[] block for page HTML (see below)
pnpm run i18n:sync
pnpm dev

init -t ui-astro-websiteでUI抽出を足場固めし、ページHTMLも翻訳する場合はdocs[]ブロックにマージします。

{
  "features": {
    "translateUIStrings": true,
    "translateDocs": true
  },
  "ui": {
    "sourceRoots": ["src/"],
    "stringsJson": "public/locales/strings.json",
    "flatOutputDir": "public/locales/"
  },
  "docs": [{
    "contentPaths": ["src/pages/index.astro"],
    "outputDir": "src/pages",
    "docsOutput": {
      "style": "astro-starlight",
      "docsRoot": "src/pages"
    },
    "addFrontmatter": false
  }]
}

言語を追加または削除する際には、3つのリストを揃えてください。ai-i18n-tools.config.json内のtargetLocales、astro.config.mjs内のi18n.locales（Astroはpt-brのような小文字のルートコードを使用します）、およびui-languages.json（generate-ui-languages経由）。フラットバンドルのファイル名は設定のケース（pt-BR.json）を使用します。Astroのpt-brルートをマニフェストのcodeフィールド経由でそのファイルにマッピングします。

ビルド時に、英語のソースリテラルをキーとして検索することでt('…')を解決します。examples/astro-website/src/i18n/t.tsを参照してください。ロード後に言語を切り替えるクライアントアイランドを追加しない限り、静的サイトではai-i18n-tools/runtimeやi18nextは必要ありません。

プロジェクト例

examples/astro-website — translate-docs経由のHTMLとt() + translate-ui経由のスクリーンショットタブラベルを備えたハイブリッドランディングページ。

プロジェクト例

プロジェクト	ユースケース	ポート
examples/astro-docs	Starlightドキュメント	3050
examples/astro-website	プレーンなAstroマーケティングサイト（HTML + t()ハイブリッド）	（READMEを参照）

examples/astro-docsとexamples/docusaurus-docsを比較してください — チュートリアルの内容は似ていますが、StarlightではなくDocusaurusの出力スタイルを採用しています。