Astro 통합

ai-i18n-tools를 Astro와 함께 두 가지 일반적인 설정에서 사용하세요. Astro Starlight 문서 사이트와 일반 Astro 마케팅 또는 앱 사이트입니다. 둘 다 페이지 콘텐츠에 Documents(translate-docs)를 사용합니다. 일반 Astro 사이트는 종종 프런트매터 및 공유 데이터의 t() 문자열에 UI 문자열(extract / translate-ui)을 결합합니다.

다음 항목도 참조하세요. UI 문자열, 문서, 아래의 실행 가능한 예시.

Astro Starlight

Astro Starlight 문서 사이트에는 init -t ui-starlight 및 docsOutput.style: "astro-starlight"을 사용하세요. 이 사전 설정은 빈 localeSubpath가 있는 doc-system의 별칭입니다. 번역된 페이지는 영어 소스 트리 옆의 src/content/docs/<locale>/ 아래에 있습니다.

빠른 시작

ai-i18n-tools init -t ui-starlight [-P <provider>]
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync   # or: ai-i18n-tools sync
pnpm dev             # Starlight dev server (project-specific script)

페이지 레이아웃

영어 마크다운 및 MDX는 Starlight 콘텐츠 루트(일반적으로 src/content/docs/)에 있습니다. 번역된 사본은 소스 트리 옆에 작성됩니다.

src/content/docs/quick-start.md     →  src/content/docs/de/quick-start.md
src/content/docs/guide/setup.mdx    →  src/content/docs/fr/guide/setup.mdx

하나의 docs[] 블록을 구성하세요:

{
  "contentPaths": ["src/content/docs/"],
  "outputDir": "src/content/docs",
  "docsOutput": {
    "style": "astro-starlight",
    "docsRoot": "src/content/docs"
  }
}

contentPaths를 영어 .md / .mdx 파일 및 디렉터리를 가리키도록 합니다. docsRoot를 Starlight가 콘텐츠 루트로 사용하는 동일한 폴더로 설정합니다.

Starlight UI 재정의는 필요한 경우 별도의 docs[] 블록에서 src/content/i18n/en.json와 jsonPathTemplate를 사용할 수 있습니다. 문서 — 문서화를 위한 초기화를 참조하세요.

Starlight는 여러 로케일에 대한 기본 제공 UI 문자열(탐색 레이블, 검색 플레이스홀더, 목차 등)을 제공합니다. 구성할 별도의 셸/테마 파이프라인이 없으며, 페이지 콘텐츠에는 translate-docs만 사용하면 됩니다. 다른 프레임워크는 프레임워크 셸 번역을 참조하세요.

예제 프로젝트

examples/astro-docs — src/content/docs/의 영어 소스, src/content/docs/<locale>/ 아래의 커밋된 번역, RTL 로케일(ar) 및 용어집 기반 번역. 포트 3050에서 pnpm dev를 실행합니다.

일반 Astro (마케팅 및 앱 사이트)

정적 Astro 마케팅 또는 앱 사이트(Starlight 아님)의 경우 Astro 내장 i18n 라우팅을 ai-i18n-tools와 결합합니다. 참조 구현은 examples/astro-website입니다. 영어는 /에, 대상 로케일은 /{locale}/에 있습니다.

대부분의 팀은 동일한 페이지에서 두 파이프라인의 하이브리드를 사용합니다.

파이프라인	용도	명령어	출력
페이지 HTML	템플릿 본문의 제목, 단락, 내비게이션 레이블, 인라인 배열	translate-docs	로케일별 src/pages/{locale}/index.astro
UI 문자열(t())	Frontmatter 데이터, 탭 레이블, 공유 배열	extract → translate-ui	public/locales/{locale}.json (영어 소스를 키로 사용)

빠른 시작

ai-i18n-tools init -t ui-astro-website [-P <provider>]
# enable features.translateDocs and add a docs[] block for page HTML (see below)
pnpm run i18n:sync
pnpm dev

init -t ui-astro-website로 UI 추출을 스캐폴드한 다음, 페이지 HTML도 번역할 때 docs[] 블록에 병합합니다.

{
  "features": {
    "translateUIStrings": true,
    "translateDocs": true
  },
  "ui": {
    "sourceRoots": ["src/"],
    "stringsJson": "public/locales/strings.json",
    "flatOutputDir": "public/locales/"
  },
  "docs": [{
    "contentPaths": ["src/pages/index.astro"],
    "outputDir": "src/pages",
    "docsOutput": {
      "style": "astro-starlight",
      "docsRoot": "src/pages"
    },
    "addFrontmatter": false
  }]
}

언어를 추가하거나 제거할 때 세 가지 목록을 정렬된 상태로 유지합니다. ai-i18n-tools.config.json의 targetLocales, astro.config.mjs의 i18n.locales(Astro는 pt-br와 같은 소문자 경로 코드를 사용합니다), 그리고 ui-languages.json(generate-ui-languages를 통해). 플랫 번들 파일 이름은 구성 대소문자(pt-BR.json)를 사용합니다. 매니페스트 code 필드를 통해 Astro의 pt-br 경로를 해당 파일에 매핑합니다.

키로 영어 원본 리터럴을 찾아 빌드 시간에 t('…')를 해결합니다. examples/astro-website/src/i18n/t.ts을 참조하세요. 로드 후 언어를 전환하는 클라이언트 아일랜드를 추가하지 않는 한 정적 사이트에는 ai-i18n-tools/runtime 또는 i18next가 필요하지 않습니다.

예제 프로젝트

examples/astro-website — translate-docs를 통한 HTML 및 t() + translate-ui를 통한 스크린샷 탭 레이블이 있는 하이브리드 랜딩 페이지입니다.

예시 프로젝트

프로젝트	사용 사례	포트
examples/astro-docs	Starlight 문서	3050
examples/astro-website	일반 Astro 마케팅 사이트 (HTML + t() 하이브리드)	(README 참조)

examples/astro-docs와 examples/docusaurus-docs를 비교해 보세요 — 유사한 튜토리얼 콘텐츠, Starlight 대신 Docusaurus 출력 스타일.