휴고 블로그, 다국어 지원으로 글로벌 확장하기 - 한세계

다국어 설정을 지원하는 Hugo 블로그 구축하기

Hugo는 다국어(Multilingual) 지원 기능이 강력한 정적 사이트 생성기입니다. 이는 다양한 국적의 사람들이 블로그를 방문하도록 돕는 중요한 기능 중 하나입니다. 자동 번역 서비스도 활용할 수 있지만, 원어로 작성된 콘텐츠의 품질은 이를 뛰어넘습니다. Hugo의 다국어 기능은 매우 매력적이지만, 이를 효과적으로 활용하려면 몇 가지 사항을 알아두어야 합니다. 아래는 다국어 지원을 설정하는 방법과 관련된 모든 내용을 단계별로 설명합니다.

1. 도메인 사용의 중요성

Hugo의 다국어 시스템은 언어 코드를 루트 디렉토리 바로 뒤에 추가하는 방식으로 작동합니다. 예를 들어, 블로그를 name.github.io/hugo에 배포하고 다국어를 지원하려고 한다면, 다음과 같은 디렉토리 구조를 기대할 수 있습니다:

name.github.io/hugo/ko
name.github.io/hugo/en
name.github.io/hugo/ja

하지만, 실제로는 루트 디렉토리 기준으로 언어 코드가 생성되어 아래와 같은 구조가 됩니다:

name.github.io/ko/hugo
name.github.io/en/hugo

이 문제를 해결하려면 루트 디렉토리 기반으로 블로그를 배포해야 합니다. 이를 위해 두 가지 방법이 있습니다:

1. GitHub name.github.io 형식의 리포지토리 생성
2. 커스텀 도메인 구매 및 연결

name.github.io 리포지토리란?

GitHub name.github.io 형식의 레포지토리는 별도의 서브디렉토리 없이 블로그를 루트 도메인에 배포할 수 있도록 도와줍니다. 이 리포지토리는 GitHub Pages에서 사용자 또는 조직의 메인 도메인으로 사용되며, 각 계정(또는 조직)당 단 하나만 생성할 수 있습니다.

생성 방법

1. GitHub에서 새 레포지토리를 생성합니다.
2. 레포지토리 이름을 name.github.io 형식으로 입력합니다(여기서 name은 GitHub 사용자명).
3. 공개(Public) 설정으로 생성하고, Hugo 테마와 콘텐츠를 배포합니다.

2. 다국어 설정을 위한 i18n 코드 이해하기

다국어 지원을 위해 Hugo는 i18n(Internationalization) 코드를 사용합니다. 각 언어는 고유한 코드로 정의되며, 이를 정확히 사용하는 것이 중요합니다.
예를 들어:

• 한국어: ko
• 영어: en
• 일본어: ja
• 중국어(간체): zh-Hans
• 프랑스어: fr

3. hugo.yaml로 다국어 설정 구성하기

Hugo의 다국어 설정은 hugo.yaml 또는 config.yaml 파일에서 정의합니다. 아래는 다국어 블로그 설정의 예입니다:

defaultContentLanguage: ko
defaultContentLanguageInSubdir: false
languages:
  ko:
    weight: 1
    languageName: 한국어
    languageCode: ko
    contentDir: content/ko/
    title: 블로그 제목
    menu:
      main:
        - name: Posts
          url: /posts/
          weight: 10
        - name: Search
          url: /search/
          weight: 20
        - name: Tags
          url: /tags/
          weight: 30

  en:
    weight: 2
    languageName: English
    languageCode: en
    contentDir: content/en/
    title: Blog Title
    menu:
      main:
        - name: Posts
          url: /posts/
          weight: 10
        - name: Search
          url: /search/
          weight: 20
        - name: Tags
          url: /tags/
          weight: 30

주요 설정 설명

• defaultContentLanguage: 기본 언어 설정 (ko = 한국어)
• defaultContentLanguageInSubdir: 기본 언어의 콘텐츠를 루트 디렉토리에 저장 여부 (false 설정 시 루트 디렉토리 사용, true 설정시 ko 디렉토리 사용)
• languages: 각 언어별 설정
  • weight: 언어 우선순위
  • languageName: 언어 표시명
  • languageCode: i18n 언어 코드
  • contentDir: 언어별 콘텐츠 디렉토리 경로

4. 다국어 콘텐츠 디렉토리 구성

Hugo는 언어별 콘텐츠를 저장할 디렉토리를 요구합니다. 예를 들어:

• 한국어 콘텐츠: content/ko/
• 영어 콘텐츠: content/en/

각 디렉토리 내에 동일한 구조로 파일을 배치하면, Hugo가 언어에 따라 콘텐츠를 자동으로 매핑합니다.

5. 다국어 메뉴 설정

다국어 웹사이트에서는 각 언어별로 동일한 메뉴 구조를 제공해야 사용자가 혼란 없이 탐색할 수 있습니다. 위 YAML 설정 예시에서 menu 항목은 한국어와 영어 모두에 대해 동일한 구조를 정의했습니다.

[!warning]
이 설정은 사용하는 테마에 따라 다를 수 있습니다. 일부 테마는 content 폴더에서 파일명.md, 파일명_en.md처럼 파일명을 구분하여 작성하기도 합니다. 따라서 테마 설명서를 참고해 정확한 방법을 확인하세요. 다만, 기본 원리는 대부분 비슷합니다.

6. 다국어 블로그 배포하기

다국어 설정을 완료한 후, 블로그를 배포하려면 아래 단계를 따라 진행합니다:

1. 변경 사항을 저장하고 배포하기 전 블로그에 문제가 없는지 확인합니다.

   hugo server
   

2. 결과물에 문제가 없다면 GitHub 메인 리포지토리 또는 커스텀 도메인에 배포합니다.

3. 배포 후 웹사이트에서 다국어 메뉴와 콘텐츠가 올바르게 작동하는지 확인합니다.

마무리

Hugo의 다국어 기능은 블로그를 전 세계로 확장할 수 있는 강력한 도구입니다. 다만, 초기 설정 단계에서 i18n 코드와 루트 디렉토리 설정을 정확히 해야 문제 없는 운영이 가능합니다. 이 글을 참고해 다국어 블로그를 성공적으로 구축하길 바랍니다.

참조

• https://gohugo.io/