Bỏ qua để đến nội dung
@aws/nx-plugin
Blog

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 pipeline dịch tự động được hỗ trợ bởi một Strands Agent trên Amazon Bedrock.

Cách sử dụng

Phần tiêu đề “Cách sử dụng”

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

Phần tiêu đề “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:

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

    Tùy chọn

    Phần tiêu đề “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.
    noTranslation boolean Từ chối quy trình dịch tài liệu tự động (Strands Agent trên Amazon Bedrock + một target dự án `translate`).
    noBlog boolean Từ chối plugin `starlight-blog` và bài viết blog mẫu.
    skipInstall boolean Bỏ qua cài đặt các dependencies sau khi generator chạy.

    Kết quả của Generator

    Phần tiêu đề “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

    Phần tiêu đề “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:

    1. Thêm một mục vào locales trong astro.config.mjs (ví dụ ko: { label: '한국어' }).
    2. Tạo một thư mục tương ứng trong src/content/docs/<locale>/.
    3. Đ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

    Phần tiêu đề “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:

    Terminal window
    pnpm nx translate docs -- --all
    pnpm nx translate docs -- --languages jp,ko
    pnpm 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ấu hình dịch thuật

    Phần tiêu đề “Cấu hình dịch thuật”

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

    TrườngMục đích
    sourceLanguageNgôn ngữ để dịch từ (mặc định en).
    targetLanguagesNgô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.
    includeCác mẫu glob (tương đối với <docsDir>/<sourceLanguage>) cho các tệp cần dịch.
    excludeCác mẫu glob để bỏ qua.
    modelIdModel Bedrock để sử dụng cho dịch thuật.
    awsRegionAWS region mà Bedrock client được cấu hình. Cũng có thể được đặt qua AWS_REGION.
    concurrencySố lượng tối đa các lời gọi agent đồng thời.
    translationCommitMessageĐánh dấ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ữ

    Phần tiêu đề “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 sự thật 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

    Phần tiêu đề “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

    Phần tiêu đề “Thiết lập CI”

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

    1. Cấu hình thông tin xác thực AWS với quyền gọi Bedrock InvokeModel trên model đã cấu hình.

    2. Chạy target translate trên các pull request chạm vào tài liệu ngôn ngữ nguồn của bạn:

      Terminal window
      pnpm nx translate docs

    3. 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ừ đó.