Astro Docs

Ce générateur crée un site de documentation propulsé par Astro et le thème de documentation Starlight. Il configure la localisation, les extraits de contenu réutilisables, les liens internes sensibles à la locale et un plugin starlight-blog par défaut.

Par défaut, il crée également un pipeline de traduction automatisé propulsé par un Strands Agent sur Amazon Bedrock.

Utilisation

Générer un site de documentation Astro

Vous pouvez générer un nouveau site de documentation Astro de deux manières :

CLI
VSCode

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

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

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

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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

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

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

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

Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
Ouvrez la console Nx dans VSCode
Cliquez sur Generate (UI) dans la section "Common Nx Commands"
Recherchez @aws/nx-plugin - ts#docs
Remplissez les paramètres requis
Cliquez sur Generate

Options

Paramètre	Type	Par défaut	Description
name Requis	string	docs	Le nom du projet de documentation.
directory	string	.	Le répertoire parent dans lequel le projet de documentation est placé.
subDirectory	string	-	Le sous-répertoire dans lequel le projet de documentation est placé. Par défaut, le nom du projet en kebab-case.
framework	astro	astro	Le framework de documentation à utiliser.
noTranslation	boolean		Désactiver le pipeline de traduction automatique de la documentation (Strands Agent sur Amazon Bedrock + une cible de projet `translate`).
noBlog	boolean		Désactiver le plugin `starlight-blog` et l'article de blog exemple.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir à false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Par défaut, le générateur crée la structure de projet suivante dans docs/ à la racine de l’espace de travail (configurable via les options name, directory et 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
Répertoirescripts
- 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)
Répertoiresrc
- Répertoirecomponents
  - link.astro Locale-aware link component (resolves paths against the current locale)
  - snippet.astro Locale-aware snippet loader component
- Répertoirecontent
  - Répertoiredocs
    Répertoireen
    index.mdx Landing page
    Répertoireguides
    getting-started.mdx Sample guide referencing the link and snippet components
    Répertoireblog
    welcome.mdx Sample blog post (omitted with --noBlog)
    Répertoiresnippets
    example.mdx Sample reusable snippet
- Répertoirestyles
  - custom.css Starlight theme overrides
README.md Project README

Localisation

Le générateur utilise par défaut une seule locale (en) et redirige l’URL racine vers celle-ci. Pour ajouter d’autres langues :

Ajoutez une entrée sous locales dans astro.config.mjs (par exemple ko: { label: '한국어' }).
Créez un répertoire correspondant sous src/content/docs/<locale>/.
Remplissez-le manuellement, ou utilisez la cible de traduction décrite ci-dessous.

Traduction

Sauf si vous avez passé --noTranslation, le générateur ajoute une cible translate à project.json, vous pouvez donc exécuter :

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

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

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

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

Lorsqu’il est exécuté sans --all, le script ne traduit que les fichiers qui ont changé depuis le dernier commit de traduction sur la branche actuelle — ce qui signifie que vous pouvez le réexécuter en toute sécurité sur chaque PR de documentation sans retraduire l’ensemble du site.

Les traductions dont le fichier source n’existe plus sont supprimées, donc renommer ou supprimer une page ne laisse pas de copies obsolètes dans chaque locale.

Chaque traduction est écrite comme un fichier complet. L’agent reçoit la source, la traduction existante et un diff de ce qui a changé, et réutilise la formulation existante pour les sections que le diff n’a pas touchées — ainsi seule la prose touchée par le diff est retraduite, et les blocs de code sont copiés de la source tels quels.

Configuration de la traduction

Modifiez scripts/translate.config.json pour changer :

Champ	Objectif
`sourceLanguage`	Locale à partir de laquelle traduire (par défaut `en`).
`targetLanguages`	Locales vers lesquelles traduire. Vide par défaut. Par exemple `["fr", "de", "es", "ja", "ko"]`.
`docsDir`	Chemin vers le répertoire de contenu de documentation, relatif à la racine du projet.
`include`	Motifs glob (relatifs à `<docsDir>/<sourceLanguage>`) pour les fichiers à traduire.
`exclude`	Motifs glob à ignorer.
`modelId`	Modèle Bedrock à utiliser pour les traductions.
`awsRegion`	Région AWS avec laquelle le client Bedrock est configuré. Peut également être défini via `AWS_REGION`.
`concurrency`	Nombre maximum d’invocations d’agent simultanées.
`translationCommitMessage`	Marqueur de message de commit pour les commits de traduction (par défaut `docs: update translations`).

Liens internes sensibles à la locale

Le générateur fournit un composant Link qui résout automatiquement les chemins de documentation internes par rapport à la locale actuelle, de sorte qu’une seule source de vérité produit la bonne URL dans chaque langue :

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

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

Extraits

Les fragments de contenu réutilisables se trouvent dans src/content/docs/<locale>/snippets/. Le composant Snippet généré charge l’extrait qui correspond à la locale actuelle :

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

<Snippet name="example" />

Configuration de la CI

Aucun workflow CI n’est généré par défaut — ajoutez-en un qui :

Configure les identifiants AWS avec la permission d’invoquer Bedrock InvokeModel sur le modèle configuré.
Exécute la cible translate sur les pull requests qui touchent vos documents en langue source :
- pnpm
- yarn
- npm
- bun
Terminal window
pnpm nx translate docs
Terminal window
yarn nx translate docs
Terminal window
npx nx translate docs
Terminal window
bunx nx translate docs
Commit les traductions résultantes dans la branche de la PR. Le message de commit doit correspondre à la valeur translationCommitMessage dans scripts/translate.config.json (par défaut docs: update translations) afin que les exécutions incrémentielles ultérieures puissent détecter le commit de référence et ne retraduire que les fichiers qui ont changé depuis.