Astro Docs

Questo generatore crea uno scheletro per un sito di documentazione basato su Astro e il tema di documentazione Starlight. Configura la localizzazione, frammenti di contenuto riutilizzabili, link interni sensibili alla lingua e un plugin starlight-blog per impostazione predefinita.

Per impostazione predefinita, crea anche una pipeline di traduzione automatizzata basata su uno Strands Agent su Amazon Bedrock.

Utilizzo

Generare un sito di documentazione Astro

Puoi generare un nuovo sito di documentazione Astro in due modi:

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

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

yarn

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

npm

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

bun

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

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - ts#docs
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	docs	Il nome del progetto di documentazione.
directory	string	.	La directory principale in cui viene posizionato il progetto di documentazione.
subDirectory	string	-	La sottodirectory in cui viene posizionato il progetto di documentazione. Per impostazione predefinita, il nome del progetto in formato kebab-case.
framework	astro	astro	Il framework di documentazione da utilizzare.
noTranslation	boolean		Rinuncia alla pipeline di traduzione automatica della documentazione (Strands Agent su Amazon Bedrock + un target di progetto `translate`).
noBlog	boolean		Rinuncia al plugin `starlight-blog` e al post di blog di esempio.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del generatore

Per impostazione predefinita, il generatore crea la seguente struttura di progetto in docs/ nella radice del workspace (configurabile tramite le opzioni name, directory e 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

Localizzazione

Il generatore utilizza per impostazione predefinita una singola lingua (en) e reindirizza l’URL radice ad essa. Per aggiungere altre lingue:

1. Aggiungi una voce sotto locales in astro.config.mjs (ad esempio ko: { label: '한국어' }).
2. Crea una directory corrispondente sotto src/content/docs/<locale>/.
3. Popolala manualmente, oppure usa il target di traduzione descritto di seguito.

Traduzione

A meno che tu non abbia passato --noTranslation, il generatore aggiunge un target translate a project.json, quindi puoi eseguire:

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

Quando eseguito senza --all, lo script traduce solo i file che sono cambiati dall’ultimo commit di traduzione sul branch corrente — il che significa che puoi eseguirlo nuovamente in sicurezza su ogni PR di documentazione senza ritradurre l’intero sito.

Le traduzioni il cui file sorgente non esiste più vengono eliminate, quindi rinominare o rimuovere una pagina non lascia copie obsolete in ogni lingua.

Ogni traduzione viene scritta come un file completo. All’agente vengono forniti il sorgente, la traduzione esistente e un diff di ciò che è cambiato, e riutilizza la formulazione esistente per le sezioni che il diff ha lasciato intatte — quindi solo il testo che il diff ha toccato viene ritradotto, e i blocchi di codice vengono copiati dal sorgente così come sono.

Configurare la traduzione

Modifica scripts/translate.config.json per cambiare:

Campo	Scopo
sourceLanguage	Lingua da cui tradurre (predefinita en).
targetLanguages	Lingue verso cui tradurre. Vuoto per impostazione predefinita. Ad esempio ["fr", "de", "es", "ja", "ko"].
docsDir	Percorso della directory del contenuto della documentazione, relativo alla radice del progetto.
include	Pattern glob (relativi a <docsDir>/<sourceLanguage>) per i file da tradurre.
exclude	Pattern glob da saltare.
modelId	Modello Bedrock da utilizzare per le traduzioni.
awsRegion	Regione AWS con cui è configurato il client Bedrock. Può anche essere impostata tramite AWS_REGION.
concurrency	Numero massimo di invocazioni simultanee dell’agente.
translationCommitMessage	Marcatore del messaggio di commit per i commit di traduzione (predefinito docs: update translations).

Link interni sensibili alla lingua

Il generatore include un componente Link che risolve automaticamente i percorsi interni della documentazione rispetto alla lingua corrente, quindi un’unica fonte di verità produce l’URL corretto in ogni lingua:

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

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

Snippet

I frammenti di contenuto riutilizzabili si trovano in src/content/docs/<locale>/snippets/. Il componente Snippet generato carica lo snippet che corrisponde alla lingua corrente:

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

<Snippet name="example" />

Configurare la CI

Nessun workflow CI viene generato di default — aggiungine uno che:

1. Configuri le credenziali AWS con il permesso di invocare InvokeModel di Bedrock sul modello configurato.

2. Esegua il target translate sulle pull request che toccano la documentazione nella lingua sorgente:

   pnpm

   pnpm nx translate docs

   yarn

   yarn nx translate docs

   npm

   npx nx translate docs

   bun

   bunx nx translate docs

3. Effettui il commit delle traduzioni risultanti nel branch della PR. Il messaggio di commit deve corrispondere al valore translationCommitMessage in scripts/translate.config.json (predefinito docs: update translations) in modo che le successive esecuzioni incrementali possano rilevare il commit di base e ritradurre solo i file che sono cambiati da allora.