Astro Docs

このジェネレーターは、Astro と Starlight ドキュメントテーマを使用したドキュメントサイトをスキャフォールドします。デフォルトで、ローカライゼーション、再利用可能なコンテンツスニペット、ロケール対応の内部リンク、および starlight-blog プラグインを設定します。

また、デフォルトで Amazon Bedrock 上の Strands Agent を使用した自動翻訳パイプラインもスキャフォールドします。

使用方法

Astro ドキュメントサイトを生成する

新しい Astro ドキュメントサイトは2つの方法で生成できます：

VSCode

1. インストール Nx Console VSCode Plugin まだインストールしていない場合
2. VSCodeでNxコンソールを開く
3. クリック Generate (UI) "Common Nx Commands"セクションで
4. 検索 @aws/nx-plugin - ts#astro-docs
5. 必須パラメータを入力
6. クリック Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#astro-docs

yarn

yarn nx g @aws/nx-plugin:ts#astro-docs

npm

npx nx g @aws/nx-plugin:ts#astro-docs

bun

bunx nx g @aws/nx-plugin:ts#astro-docs

変更されるファイルを確認するためにドライランを実行することもできます

pnpm

pnpm nx g @aws/nx-plugin:ts#astro-docs --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#astro-docs --dry-run

npm

npx nx g @aws/nx-plugin:ts#astro-docs --dry-run

bun

bunx nx g @aws/nx-plugin:ts#astro-docs --dry-run

オプション

パラメータ	型	デフォルト	説明
name 必須	string	docs	ドキュメントプロジェクトの名前。
directory	string	.	ドキュメントプロジェクトが配置される親ディレクトリ。
subDirectory	string	-	ドキュメントプロジェクトが配置されるサブディレクトリ。デフォルトはケバブケースのプロジェクト名。
noTranslation	boolean		自動ドキュメント翻訳パイプライン（Amazon Bedrock上のStrands Agentと`translate`プロジェクトターゲット）をオプトアウトする。
noBlog	boolean		`starlight-blog`プラグインとサンプルブログ投稿をオプトアウトする。
skipInstall	boolean		ジェネレーター実行後の依存関係のインストールをスキップする。

ジェネレーターの出力

デフォルトでは、ジェネレーターはワークスペースルートの docs/ に以下のプロジェクト構造を作成します（name、directory、subDirectory オプションで設定可能）：

• astro.config.mjs Astro + Starlight の設定（ロケール、サイドバー、ブログプラグイン）
• tsconfig.json @components / @assets パスエイリアスを含む astro/tsconfigs/strict を拡張
• project.json build、start、preview（有効な場合は translate）ターゲットを持つ Nx プロジェクト
• Directoryscripts

  • translate.ts 翻訳ドライバー — スコープ付きファイルエディターツールを持つ Strands エージェント（--noTranslation で省略）
  • translate.config.json ソース/ターゲットロケール、glob パターン、モデル ID、リージョン（--noTranslation で省略）
• Directorysrc

  • Directorycomponents

    • link.astro ロケール対応リンクコンポーネント（現在のロケールに対してパスを解決）
    • snippet.astro ロケール対応スニペットローダーコンポーネント
  • Directorycontent

    • Directorydocs

      • Directoryen

        • index.mdx ランディングページ
        • Directoryguides

          • getting-started.mdx リンクとスニペットコンポーネントを参照するサンプルガイド
        • Directoryblog

          • welcome.mdx サンプルブログ投稿（--noBlog で省略）
        • Directorysnippets

          • example.mdx 再利用可能なサンプルスニペット
  • Directorystyles

    • custom.css Starlight テーマのオーバーライド
• README.md プロジェクト README

ローカライゼーション

ジェネレーターはデフォルトで単一のロケール（en）を使用し、ルート URL をそこにリダイレクトします。さらに言語を追加するには：

1. astro.config.mjs の locales にエントリを追加します（例：ko: { label: '한국어' }）。
2. src/content/docs/<locale>/ の下に対応するディレクトリを作成します。
3. 手動で入力するか、以下で説明する翻訳ターゲットを使用します。

翻訳

--noTranslation を渡さない限り、ジェネレーターは project.json に translate ターゲットを追加するため、以下を実行できます：

pnpm

pnpm nx translate docs -- --all
pnpm nx translate docs -- --languages jp,ko
pnpm nx translate docs -- --dry-run

yarn

yarn nx translate docs -- --all
yarn nx translate docs -- --languages jp,ko
yarn nx translate docs -- --dry-run

npm

npx nx translate docs -- --all
npx nx translate docs -- --languages jp,ko
npx nx translate docs -- --dry-run

bun

bunx nx translate docs -- --all
bunx nx translate docs -- --languages jp,ko
bunx nx translate docs -- --dry-run

--all なしで実行すると、スクリプトは現在のブランチで最後の翻訳コミット以降に変更されたファイルのみを翻訳します。つまり、サイト全体を再翻訳することなく、すべてのドキュメント PR で安全に再実行できます。

翻訳の設定

scripts/translate.config.json を編集して以下を変更します：

フィールド	目的
sourceLanguage	翻訳元のロケール（デフォルトは en）。
targetLanguages	翻訳先のロケール。デフォルトでは空です。例：["fr", "de", "es", "ja", "ko"]。
docsDir	プロジェクトルートからの相対的なドキュメントコンテンツディレクトリへのパス。
include	翻訳するファイルの glob パターン（<docsDir>/<sourceLanguage> からの相対パス）。
exclude	スキップする glob パターン。
modelId	翻訳に使用する Bedrock モデル。
awsRegion	Bedrock クライアントが設定されている AWS リージョン。AWS_REGION 経由でも設定可能。
concurrency	同時エージェント呼び出しの最大数。
translationCommitMessage	翻訳コミットのコミットメッセージマーカー（デフォルトは docs: update translations）。

ロケール対応の内部リンク

ジェネレーターには、現在のロケールに対して内部ドキュメントパスを自動的に解決する Link コンポーネントが付属しているため、単一の情報源がすべての言語で正しい URL を生成します：

import Link from '@components/link.astro';

<Link path="guides/getting-started">Read the getting-started guide</Link>

スニペット

再利用可能なコンテンツフラグメントは src/content/docs/<locale>/snippets/ にあります。生成された Snippet コンポーネントは、現在のロケールに一致するスニペットを読み込みます：

import Snippet from '@components/snippet.astro';

<Snippet name="example" />

CI の設定

デフォルトでは CI ワークフローは生成されません。以下を行うワークフローを追加してください：

1. 設定されたモデルで Bedrock InvokeModel を呼び出す権限を持つ AWS 認証情報を設定します。

2. ソース言語のドキュメントに触れるプルリクエストで translate ターゲットを実行します：

   pnpm

   pnpm nx translate docs

   yarn

   yarn nx translate docs

   npm

   npx nx translate docs

   bun

   bunx nx translate docs

3. 結果の翻訳を PR ブランチにコミットバックします。コミットメッセージは scripts/translate.config.json の translationCommitMessage 値（デフォルトは docs: update translations）と一致する必要があります。これにより、後続の増分実行がベースラインコミットを検出し、それ以降に変更されたファイルのみを再翻訳できます。