Skip to content
@aws/nx-plugin
Blog

Astro Docs

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

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

使用方法

Section titled “使用方法”

Astro ドキュメントサイトの生成

Section titled “Astro ドキュメントサイトの生成”

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

Terminal window
pnpm nx g @aws/nx-plugin:ts#docs
変更されるファイルを確認するためにドライランを実行することもできます
Terminal window
pnpm nx g @aws/nx-plugin:ts#docs --dry-run

オプション

Section titled “オプション”
パラメータ型デフォルト説明
name 必須stringdocsドキュメントプロジェクトの名前。
directory string.ドキュメントプロジェクトが配置される親ディレクトリ。
subDirectory string-ドキュメントプロジェクトが配置されるサブディレクトリ。デフォルトはケバブケースのプロジェクト名。
framework astroastro使用するドキュメントフレームワーク。
noTranslation boolean自動ドキュメント翻訳パイプライン（Strands Agent on Amazon Bedrock + `translate` プロジェクトターゲット）をオプトアウトする。
noBlog boolean`starlight-blog` プラグインとサンプルブログ投稿をオプトアウトする。
preferInstallDependencies booleantrueジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

Section titled “ジェネレーターの出力”

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

  • astro.config.mjs Astro + Starlight configuration (locales, sidebar, blog plugin)
  • tsconfig.json Extends astro/tsconfigs/strict with @components / @assets path aliases
  • project.json Nx project with build, start, preview (and translate if enabled) targets
  • Directoryscripts
    • translate.ts Translation driver — a Strands agent with a scoped file-editor tool (omitted with --noTranslation)
    • translate.config.json Source/target locales, glob patterns, model id, region (omitted with --noTranslation)
  • Directorysrc
    • Directorycomponents
      • link.astro Locale-aware link component (resolves paths against the current locale)
      • snippet.astro Locale-aware snippet loader component
    • Directorycontent
      • Directorydocs
        • Directoryen
          • index.mdx Landing page
          • Directoryguides
            • getting-started.mdx Sample guide referencing the link and snippet components
          • Directoryblog
            • welcome.mdx Sample blog post (omitted with --noBlog)
          • Directorysnippets
            • example.mdx Sample reusable snippet
    • Directorystyles
      • custom.css Starlight theme overrides
  • README.md Project README

ローカライゼーション

Section titled “ローカライゼーション”

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

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

翻訳

Section titled “翻訳”

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

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

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

ソースファイルが存在しなくなった翻訳は削除されるため、ページの名前変更や削除によって各ロケールに古いコピーが残ることはありません。

各翻訳はファイル全体として書き込まれます。エージェントにはソース、既存の翻訳、および変更内容の差分が与えられ、差分が変更しなかったセクションについては既存の文言を再利用します。そのため、差分が触れた散文のみが再翻訳され、コードブロックはソースからそのままコピーされます。

翻訳の設定

Section titled “翻訳の設定”

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

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

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

Section titled “ロケール対応の内部リンク”

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

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


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

スニペット

Section titled “スニペット”

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

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


<Snippet name="example" />

CI の設定

Section titled “CI の設定”

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

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

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

    Terminal window
    pnpm nx translate docs

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