Astro Docs

이 생성기는 Astro와 Starlight 문서 테마로 구동되는 문서 사이트를 스캐폴딩합니다. 기본적으로 로컬라이제이션, 재사용 가능한 콘텐츠 스니펫, 로케일 인식 내부 링크 및 starlight-blog 플러그인을 연결합니다.

기본적으로 Amazon Bedrock의 Strands Agent로 구동되는 자동 번역 파이프라인도 스캐폴딩합니다.

사용법

Astro 문서 사이트 생성

두 가지 방법으로 새로운 Astro 문서 사이트를 생성할 수 있습니다:

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

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

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. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#docs
5. 필수 매개변수 입력
6. 클릭 Generate

옵션

매개변수	타입	기본값	설명
name 필수	string	docs	문서 프로젝트의 이름입니다.
directory	string	.	문서 프로젝트가 배치될 상위 디렉토리입니다.
subDirectory	string	-	문서 프로젝트가 배치될 하위 디렉토리입니다. 기본값은 케밥 케이스 프로젝트 이름입니다.
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을 해당 로케일로 리디렉션합니다. 더 많은 언어를 추가하려면:

1. astro.config.mjs의 locales 아래에 항목을 추가합니다(예: ko: { label: '한국어' }).
2. src/content/docs/<locale>/ 아래에 일치하는 디렉토리를 생성합니다.
3. 수동으로 채우거나 아래에 설명된 번역 타겟을 사용합니다.

번역

--noTranslation을 전달하지 않은 경우, 생성기는 project.json에 translate 타겟을 추가하므로 다음을 실행할 수 있습니다:

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

--all 없이 실행하면 스크립트는 현재 브랜치의 마지막 번역 커밋 이후 변경된 파일만 번역합니다. 즉, 전체 사이트를 다시 번역하지 않고도 모든 문서 PR에서 안전하게 다시 실행할 수 있습니다.

소스 파일이 더 이상 존재하지 않는 번역은 삭제되므로 페이지 이름을 변경하거나 제거해도 각 로케일에 오래된 복사본이 남지 않습니다.

각 번역은 전체 파일로 작성됩니다. 에이전트는 소스, 기존 번역 및 변경 사항의 diff를 받고, diff가 건드리지 않은 섹션에 대해서는 기존 표현을 재사용합니다. 따라서 diff가 건드린 산문만 다시 번역되고 코드 블록은 소스에서 그대로 복사됩니다.

번역 구성

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 연결

기본적으로 CI 워크플로는 생성되지 않습니다. 다음을 수행하는 워크플로를 추가하세요:

1. 구성된 모델에서 Bedrock InvokeModel을 호출할 수 있는 권한으로 AWS 자격 증명을 구성합니다.

2. 소스 언어 문서를 건드리는 풀 리퀘스트에서 translate 타겟을 실행합니다:

   pnpm

   pnpm nx translate docs

   yarn

   yarn nx translate docs

   npm

   npx nx translate docs

   bun

   bunx nx translate docs

3. 결과 번역을 PR 브랜치에 다시 커밋합니다. 커밋 메시지는 scripts/translate.config.json의 translationCommitMessage 값(기본값 docs: update translations)과 일치해야 하므로 후속 증분 실행이 기준 커밋을 감지하고 그 이후 변경된 파일만 다시 번역할 수 있습니다.