Astro Docs

此生成器搭建一个由 Astro 和 Starlight 文档主题驱动的文档站点。它默认配置了本地化、可重用的内容片段、区域感知的内部链接以及 starlight-blog 插件。

默认情况下，它还会搭建一个由 Amazon Bedrock 上的 Strands Agent 驱动的自动翻译管道。

用法

您可以通过两种方式生成新的 Astro 文档站点：

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

您还可以执行试运行以查看哪些文件会被更改

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

参数	类型	默认值	描述
name 必需	string	docs	文档项目的名称。
directory	string	.	文档项目所在的父目录。
subDirectory	string	-	文档项目所在的子目录。默认为 kebab-case 格式的项目名称。
framework	astro	astro	要使用的文档框架。
noTranslation	boolean		选择退出自动文档翻译管道（Amazon Bedrock 上的 Strands Agent + `translate` 项目目标）。
noBlog	boolean		选择退出 `starlight-blog` 插件和示例博客文章。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

默认情况下，生成器会在工作区根目录的 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
文件夹scripts
- 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)
文件夹src
- 文件夹components
  - link.astro Locale-aware link component (resolves paths against the current locale)
  - snippet.astro Locale-aware snippet loader component
- 文件夹content
  - 文件夹docs
    文件夹en
    index.mdx Landing page
    文件夹guides
    getting-started.mdx Sample guide referencing the link and snippet components
    文件夹blog
    welcome.mdx Sample blog post (omitted with --noBlog)
    文件夹snippets
    example.mdx Sample reusable snippet
- 文件夹styles
  - custom.css Starlight theme overrides
README.md Project README

生成器默认使用单一语言环境（en）并将根 URL 重定向到它。要添加更多语言：

除非您传递了 --noTranslation，否则生成器会向 project.json 添加一个 translate 目标，因此您可以运行：

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

在不使用 --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 工作流——添加一个工作流来：

配置 AWS 凭证，具有在配置的模型上调用 Bedrock InvokeModel 的权限。
在触及源语言文档的拉取请求上运行 translate 目标：
- 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
将生成的翻译提交回 PR 分支。提交消息必须与 scripts/translate.config.json 中的 translationCommitMessage 值匹配（默认为 docs: update translations），以便后续的增量运行可以检测基线提交，并仅重新翻译自那时以来更改的文件。