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 :

Exécuter ce générateur@aws/nx-plugin:ts#docs

CLI

pnpm

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

yarn

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

npm

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

bun

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

VSCode

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

Composez votre commande7

nameRequis

directory

framework

astro

subDirectory

noTranslation

false

noBlog

false

preferInstallDependencies

true

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Options

Options du générateur7 options

nameRequisstringPar défaut: docs

Le nom du projet de documentation.

directorystringPar défaut: .

Le répertoire parent dans lequel le projet de documentation est placé.

frameworkenumPar défaut: astro

Le framework de documentation à utiliser.

astro

subDirectorystring

Le sous-répertoire dans lequel le projet de documentation est placé. Par défaut, le nom du projet en kebab-case.

noTranslationbooleanPar défaut: false

Désactiver le pipeline de traduction automatique de la documentation (Strands Agent sur Amazon Bedrock + une cible de projet `translate`).

noBlogbooleanPar défaut: false

Désactiver le plugin `starlight-blog` et l'article de blog exemple.

preferInstallDependenciesbooleanPar défaut: 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)
• .gitignore Ignores Astro’s build output and generated types
• Répertoiresrc

  • content.config.ts Starlight’s docs content collection definition
  • 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 :

1. Ajoutez une entrée sous locales dans astro.config.mjs (par exemple ko: { label: '한국어' }).
2. Créez un répertoire correspondant sous src/content/docs/<locale>/.
3. 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. Les locales vers lesquelles il traduit proviennent de targetLanguages dans scripts/translate.config.json, qui est vide par défaut — commencez donc par nommer les locales que vous souhaitez sur la ligne de commande :

pnpm

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

yarn

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

npm

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

bun

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

Une fois que vous avez rempli targetLanguages (voir Configuration de la traduction), --languages devient optionnel et les locales configurées sont utilisées :

pnpm

pnpm nx translate docs -- --all
pnpm nx translate docs -- --dry-run

yarn

yarn nx translate docs -- --all
yarn nx translate docs -- --dry-run

npm

npx nx translate docs -- --all
npx nx translate docs -- --dry-run

bun

bunx nx translate docs -- --all
bunx nx translate docs -- --dry-run

Configurez d’abord vos langues cibles

Sans --languages et avec targetLanguages toujours vide, la cible se termine avec un code non nul et le message ERROR No target languages configured.

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 :

1. Configure les identifiants AWS avec la permission d’invoquer Bedrock InvokeModel sur le modèle configuré.

2. Exécute la cible translate sur les pull requests qui touchent vos documents en langue source :

   pnpm

   pnpm nx translate docs

   yarn

   yarn nx translate docs

   npm

   npx nx translate docs

   bun

   bunx nx translate docs

3. Commit les traductions résultantes dans la branche de la PR, en utilisant docs: update translations comme message de commit, 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. Pour utiliser un message différent, ajoutez une clé translationCommitMessage à scripts/translate.config.json et faites correspondre cette valeur à la place.