Skip to main content
BarodocBarodoc
GitHub
3 min read

가이드

다국어 지원

Barodoc 다국어(i18n) 설정 가이드

Barodoc은 여러 언어로 문서를 작성할 수 있습니다.

Locale 폴더 구조

Locale 폴더는 필수입니다. 단일 언어여도 locale 폴더를 사용해야 합니다.

단일 언어 (예: 한국어만)

docs/src/content/docs/
└── ko/                    # 필수
    ├── introduction.mdx
    └── guides/
        └── installation.mdx

다국어

docs/src/content/docs/
├── ko/                    # 기본 언어
│   ├── introduction.mdx
│   └── guides/
│       └── installation.mdx
└── en/                    # 추가 언어
    ├── introduction.mdx
    └── guides/
        └── installation.mdx

Locale 폴더가 필수인 이유

  1. 일관성 - 모든 프로젝트가 동일한 구조
  2. 확장성 - 다국어 추가 시 구조 변경 불필요
  3. 명확한 분리 - 언어별 콘텐츠가 명확히 구분됨

단일 언어 설정

한국어만 사용하는 경우:

1. barodoc.config.json

{
  "i18n": {
    "defaultLocale": "ko",
    "locales": ["ko"]
  }
}

2. astro.config.mjs

export default defineConfig({
  i18n: {
    defaultLocale: "ko",
    locales: ["ko"],
    routing: {
      prefixDefaultLocale: false,
    },
  },
  // ...
});

결과 URL

파일 경로URL
docs/ko/introduction.mdx/docs/introduction
docs/ko/guides/install.mdx/docs/guides/install

prefixDefaultLocale: false이므로 기본 언어는 URL에 /ko/가 붙지 않습니다.

다국어 설정

1. barodoc.config.json

{
  "i18n": {
    "defaultLocale": "ko",
    "locales": ["ko", "en"],
    "labels": {
      "ko": "한국어",
      "en": "English"
    }
  }
}

2. astro.config.mjs

중요: Astro 5.x에서는 i18n을 astro.config.mjs에 직접 설정해야 합니다.

export default defineConfig({
  i18n: {
    defaultLocale: "ko",
    locales: ["ko", "en"],
    routing: {
      prefixDefaultLocale: false,
    },
  },
  // ...
});

결과 URL

파일 경로URL
docs/ko/introduction.mdx/docs/introduction (기본)
docs/en/introduction.mdx/en/docs/introduction

네비게이션 번역

group:LOCALE 패턴으로 그룹 이름을 번역합니다:

{
  "navigation": [
    {
      "group": "시작하기",
      "group:en": "Getting Started",
      "pages": ["introduction", "quickstart"]
    }
  ]
}

URL 구조

언어URL
기본 언어 (ko)/docs/introduction
영어/en/docs/introduction

prefixDefaultLocale: false 설정으로 기본 언어에는 접두사가 붙지 않습니다.

언어 전환

헤더의 언어 선택기를 통해 언어를 전환할 수 있습니다. 현재 페이지의 다른 언어 버전으로 자동 이동합니다.

새 언어 추가하기

  1. barodoc.config.json에 로케일 추가
  2. astro.config.mjs에 로케일 추가
  3. docs/src/content/docs/ 아래에 언어 폴더 생성
  4. 번역된 문서 파일 작성
  5. 네비게이션 그룹 이름 번역 추가

Linked pages