Astro Docs

Generator này tạo khung cho một trang tài liệu được hỗ trợ bởi Astro và theme tài liệu Starlight. Nó thiết lập sẵn bản địa hóa, các đoạn nội dung có thể tái sử dụng, liên kết nội bộ nhận biết ngôn ngữ và một plugin starlight-blog theo mặc định.

Theo mặc định, nó cũng tạo khung cho một quy trình dịch tự động được hỗ trợ bởi một Strands Agent trên Amazon Bedrock.

Cách sử dụng

Tạo một trang tài liệu Astro

Bạn có thể tạo một trang tài liệu Astro mới theo hai cách:

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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
Mở Nx Console trong VSCode
Nhấp Generate (UI) trong phần "Common Nx Commands"
Tìm kiếm @aws/nx-plugin - ts#docs
Điền các tham số bắt buộc
Nhấp Generate

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	docs	Tên của dự án tài liệu.
directory	string	.	Thư mục cha mà dự án tài liệu được đặt trong đó.
subDirectory	string	-	Thư mục con mà dự án tài liệu được đặt trong đó. Mặc định là tên dự án dạng kebab-case.
framework	astro	astro	Framework tài liệu sẽ sử dụng.
noTranslation	boolean		Từ chối quy trình dịch tài liệu tự động (Strands Agent trên Amazon Bedrock + target dự án `translate`).
noBlog	boolean		Từ chối plugin `starlight-blog` và bài viết blog mẫu.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của Generator

Theo mặc định, generator tạo cấu trúc dự án sau tại docs/ trong thư mục gốc của workspace (có thể cấu hình thông qua các tùy chọn name, directory và subDirectory):

astro.config.mjs Cấu hình Astro + Starlight (locales, sidebar, blog plugin)
tsconfig.json Mở rộng astro/tsconfigs/strict với các alias đường dẫn @components / @assets
project.json Dự án Nx với các target build, start, preview (và translate nếu được bật)
Thư mụcscripts
- translate.ts Trình điều khiển dịch — một Strands agent với công cụ file-editor có phạm vi (bỏ qua với --noTranslation)
- translate.config.json Ngôn ngữ nguồn/đích, các mẫu glob, model id, region (bỏ qua với --noTranslation)
Thư mụcsrc
- Thư mụccomponents
  - link.astro Component liên kết nhận biết ngôn ngữ (phân giải đường dẫn theo ngôn ngữ hiện tại)
  - snippet.astro Component tải snippet nhận biết ngôn ngữ
- Thư mụccontent
  - Thư mụcdocs
    Thư mụcen
    index.mdx Trang đích
    Thư mụcguides
    getting-started.mdx Hướng dẫn mẫu tham chiếu các component link và snippet
    Thư mụcblog
    welcome.mdx Bài viết blog mẫu (bỏ qua với --noBlog)
    Thư mụcsnippets
    example.mdx Snippet có thể tái sử dụng mẫu
- Thư mụcstyles
  - custom.css Ghi đè theme Starlight
README.md README của dự án

Bản địa hóa

Generator mặc định sử dụng một ngôn ngữ duy nhất (en) và chuyển hướng URL gốc đến nó. Để thêm nhiều ngôn ngữ hơn:

Thêm một mục vào locales trong astro.config.mjs (ví dụ ko: { label: '한국어' }).
Tạo một thư mục tương ứng trong src/content/docs/<locale>/.
Điền nội dung thủ công, hoặc sử dụng target dịch được mô tả bên dưới.

Dịch thuật

Trừ khi bạn truyền --noTranslation, generator sẽ thêm một target translate vào project.json, vì vậy bạn có thể chạy:

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

Khi chạy mà không có --all, script chỉ dịch các tệp đã thay đổi kể từ commit dịch cuối cùng trên nhánh hiện tại — nghĩa là bạn có thể chạy lại một cách an toàn trên mọi PR tài liệu mà không cần dịch lại toàn bộ trang.

Các bản dịch mà tệp nguồn không còn tồn tại sẽ bị xóa, vì vậy việc đổi tên hoặc xóa một trang sẽ không để lại các bản sao cũ trong mỗi ngôn ngữ.

Mỗi bản dịch được viết dưới dạng một tệp hoàn chỉnh. Agent được cung cấp nguồn, bản dịch hiện có và một diff về những gì đã thay đổi, và tái sử dụng cách diễn đạt hiện có cho các phần mà diff không chạm đến — vì vậy chỉ có văn bản mà diff chạm đến mới được dịch lại, và các khối code được sao chép từ nguồn nguyên trạng.

Cấu hình dịch thuật

Chỉnh sửa scripts/translate.config.json để thay đổi:

Trường	Mục đích
`sourceLanguage`	Ngôn ngữ để dịch từ (mặc định `en`).
`targetLanguages`	Ngôn ngữ để dịch sang. Mặc định trống. Ví dụ `["fr", "de", "es", "ja", "ko"]`.
`docsDir`	Đường dẫn đến thư mục nội dung tài liệu, tương đối với thư mục gốc của dự án.
`include`	Các mẫu glob (tương đối với `<docsDir>/<sourceLanguage>`) cho các tệp cần dịch.
`exclude`	Các mẫu glob cần bỏ qua.
`modelId`	Mô hình Bedrock sử dụng cho dịch thuật.
`awsRegion`	Vùng AWS mà Bedrock client được cấu hình. Cũng có thể được đặt qua `AWS_REGION`.
`concurrency`	Số lượng tối đa các lời gọi agent đồng thời.
`translationCommitMessage`	Dấu hiệu thông điệp commit cho các commit dịch (mặc định `docs: update translations`).

Liên kết nội bộ nhận biết ngôn ngữ

Generator cung cấp một component Link tự động phân giải các đường dẫn tài liệu nội bộ theo ngôn ngữ hiện tại, vì vậy một nguồn chân lý duy nhất tạo ra URL đúng trong mọi ngôn ngữ:

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

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

Snippets

Các đoạn nội dung có thể tái sử dụng nằm trong src/content/docs/<locale>/snippets/. Component Snippet được tạo sẽ tải snippet khớp với ngôn ngữ hiện tại:

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

<Snippet name="example" />

Thiết lập CI

Không có workflow CI nào được tạo sẵn — hãy thêm một workflow:

Cấu hình thông tin xác thực AWS với quyền gọi Bedrock InvokeModel trên mô hình đã cấu hình.
Chạy target translate trên các pull request chạm đến tài liệu ngôn ngữ nguồn của bạn:
- 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 các bản dịch kết quả trở lại nhánh PR. Thông điệp commit phải khớp với giá trị translationCommitMessage trong scripts/translate.config.json (mặc định docs: update translations) để các lần chạy tăng dần tiếp theo có thể phát hiện commit cơ sở và chỉ dịch lại các tệp đã thay đổi kể từ đó.