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

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

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

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

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

이번 글은 언어를 추가하고, 번역 파일을 연결하고, 버전별 문서를 함께 유지하는 데까지 다루겠습니다.

언어 추가하기 #

다국어는 Hugo의 기본 기능이라 테마와 무관하게 동작합니다. hugo.yaml에 언어를 선언합니다.

hugo.yaml — 언어 설정 
defaultContentLanguage: ko
defaultContentLanguageInSubdir: true

languages:
  ko:
    languageName: 한국어
    weight: 1
  en:
    languageName: English
    weight: 2

defaultContentLanguageInSubdir: true를 주면 기본 언어도 /ko/ 아래로 들어가, 모든 언어가 같은 규칙으로 정렬됩니다. 언어가 둘 이상이 되면 Hextra는 상단에 언어 전환 메뉴를 자동으로 띄웁니다.

번역 파일 두기 #

같은 문서의 언어별 버전은 파일명 뒤에 언어 코드를 붙여 나란히 둡니다.

번역 파일 두기 
content/docs/
├─ getting-started.md       # 기본 언어(한국어)
└─ getting-started.en.md    # 영어

파일 이름이 같고 위치가 같으면 Hugo가 둘을 같은 글의 번역으로 자동 인식합니다. 만약 언어별로 slug를 다르게 가져가야 한다면, 파일명 대신 translationKey로 묶습니다.

translationKey로 묶기 
---
title: 시작하기
translationKey: getting-started
---

영어 파일에도 같은 translationKey를 적어 두면, 이름이 달라도 같은 글의 번역으로 연결됩니다. 사이드바 라벨이나 버튼 같은 UI 문자열은 i18n 폴더의 번역 테이블에서 언어별로 채웁니다.

버전 관리 — 정해진 정답은 없다 #

여기서 한 가지 솔직히 짚을 점이 있습니다. Hugo에는 문서 버전 관리 기능이 기본으로 없습니다. Docusaurus가 버전 스냅샷과 버전 선택 드롭다운을 내장으로 제공하는 것과 다른 지점입니다. 그래서 Hugo에서는 버전을 폴더로 직접 나눕니다.

버전별 폴더 
content/docs/
├─ v2/          # 최신
│  ├─ _index.md
│  └─ getting-started.md
└─ v1/          # 지난 버전
   ├─ _index.md
   └─ getting-started.md

그리고 상단 메뉴에 각 버전으로 가는 링크를 둬, 독자가 직접 버전을 고르게 합니다.

hugo.yaml — 버전 메뉴 
menu:
  main:
    - name: v2 (최신)
      pageRef: /docs/v2
      weight: 1
    - name: v1
      pageRef: /docs/v1
      weight: 2

버전이 두세 개 정도면 이 방식으로 충분합니다. 다만 버전마다 “이 페이지의 다른 버전” 같은 정교한 연결이 필요하거나 버전이 계속 늘어난다면, 그 기능을 내장한 Docusaurus가 더 맞을 수 있습니다. 도구 선택은 결국 이런 요구가 얼마나 강한지에 달려 있습니다.

마무리 #

이번 글에서는 언어를 추가해 번역 파일을 연결하고, 버전을 폴더로 나눠 함께 유지하는 법을 다뤘습니다. 다국어는 Hugo가 잘 받쳐 주는 영역이고, 버전 관리는 손이 조금 가지만 폴더 분리로 현실적인 선에서 해결됩니다.

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

X