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

프레임워크 Docusaurus Documentation Static Site
3 분 소요

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

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

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

이번 글은 언어를 추가하고, 버전을 스냅샷으로 박는 데까지 다루겠습니다. 둘 다 플러그인 없이 기본 기능으로 됩니다.

언어 추가하기 — 내장 i18n #

다국어는 docusaurus.config.js에 언어를 선언하는 것으로 시작합니다.

docusaurus.config.js — 다국어 
export default {
  i18n: {
    defaultLocale: 'ko',
    locales: ['ko', 'en'],
  },
};

그다음 번역할 텍스트의 틀을 뽑아냅니다. 이 명령이 UI 문자열과 문서의 번역 자리를 i18n 폴더에 만들어 줍니다.

번역 틀 생성 
npm run write-translations -- --locale en

영어 문서는 i18n/en/docusaurus-plugin-content-docs/current/ 아래에 같은 파일명으로 두고 번역합니다. 특정 언어로 미리 보려면 --locale을 붙여 실행합니다.

영어로 미리보기 
npm run start -- --locale en

상단 메뉴에 언어 선택 드롭다운을 더하려면 navbar에 localeDropdown 항목을 넣으면 됩니다.

버전 관리 — 내장 versioning #

여기서 Docusaurus는 다른 도구들보다 한 발 앞서 있습니다. Hugo 편에서는 버전 관리 기능이 없어 폴더로 나눠야 했고, MkDocs 편에서는 mike라는 별도 도구를 붙였습니다. Docusaurus는 명령 하나로 현재 문서를 통째로 스냅샷으로 박습니다.

현재 문서를 1.0으로 박기 
npm run docusaurus docs:version 1.0

이 명령은 지금의 docs 내용을 versioned_docs/version-1.0으로 복사해 동결합니다. 이후 docs를 고치면 그것은 다음 버전이 되고, 1.0 문서는 그대로 남습니다. 상단에 버전 선택 드롭다운을 더하려면 navbar에 항목을 넣습니다.

docusaurus.config.js — 버전 드롭다운 
navbar: {
  items: [
    { type: 'docsVersionDropdown', position: 'left' },
  ],
}

제품이 2.0으로 올라가면 docs:version 2.0으로 새 스냅샷을 박으면 됩니다. 독자는 드롭다운에서 자기 버전을 골라 볼 수 있습니다.

마무리 #

이번 글에서는 내장 i18n으로 언어를 추가하고, 내장 versioning으로 버전을 스냅샷으로 박았습니다. 다국어와 버전 관리를 모두 기본으로 갖춘 점이 Docusaurus를 큰 규모의 제품 문서에서 강하게 만드는 이유입니다.

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

X