Starlight로 매뉴얼 만들기 #5 다국어와 버전 관리

프레임워크 Starlight Documentation Static Site
2 분 소요

#4에서 문서를 인터넷에 올렸습니다. 사용자가 늘면 두 가지 요구가 따라옵니다. 하나는 다른 언어로도 보고 싶다는 것이고, 다른 하나는 옛 버전 제품을 쓰는 사람을 위해 지난 문서도 남겨 달라는 것입니다. 이번 글은 그 둘을 다룹니다.

이번 시리즈는 Starlight로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지
  • #2 사이드바와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, asides
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기
  • #5 다국어와 버전 관리 ← 이번 글
  • #6 유지보수 — 검색, 접근성, 문서 문화

이번 글은 언어를 추가하고, 버전을 관리하는 데까지 다루겠습니다.

언어 추가하기 — 내장 i18n #

다국어는 Starlight가 기본으로 갖춘 기능입니다. astro.config.mjs의 Starlight 통합에 언어를 선언합니다.

astro.config.mjs — 다국어 
starlight({
  title: '제품 매뉴얼',
  defaultLocale: 'ko',
  locales: {
    ko: { label: '한국어' },
    en: { label: 'English', lang: 'en' },
  },
})

문서는 언어별 폴더에 같은 이름으로 둡니다.

번역 파일 두기 
src/content/docs/
├─ ko/
│  └─ guides/install.md   # 한국어
└─ en/
   └─ guides/install.md   # 영어

이렇게 두면 Starlight가 둘을 같은 글의 번역으로 인식하고, 상단에 언어 전환 메뉴를 자동으로 띄웁니다. 번역하지 않은 글은 기본 언어로 대체되므로, 한 번에 전부 번역하지 않아도 사이트가 깨지지 않습니다.

버전 관리 — 플러그인으로 #

여기서는 솔직히 짚을 점이 있습니다. Starlight 코어에는 버전 관리 기능이 없습니다. Docusaurus가 버전을 내장한 것과 다른 지점입니다. 대신 starlight-versions 같은 커뮤니티 플러그인으로 더합니다.

버전 플러그인 설치 
npm install starlight-versions

플러그인을 Starlight 통합의 plugins에 등록하면, 현재 문서를 버전으로 동결하고 상단에 버전 선택기를 붙일 수 있습니다. 버전 요구가 강하다면, 같은 기능을 코어로 갖춘 Docusaurus와 비교해 보는 것이 좋습니다. 도구별 버전 관리 방식의 차이는 문서 사이트 생성기 비교 글에 정리해 두었습니다.

마무리 #

이번 글에서는 내장 i18n으로 언어를 추가하고, 플러그인으로 버전 관리를 더했습니다. 다국어는 손쉽게 해결되고, 버전 관리는 한 단계 손이 가지만 플러그인으로 보완할 수 있다는 점을 확인했습니다.

다음 편은 마지막입니다. 검색, 접근성, 그리고 문서를 오래 살아 있게 하는 습관까지 운영 관점을 정리하며 시리즈를 닫겠습니다.

X