📌 들어가기

영어 버전으로 docs를 작성하다가 한글 버전으로도 docs를 작성하기 위해서 기존 en에서 ko-kr 문서를 추가했습니다.
Docusaurus에서는 공식 문서에서 Internationalization(국제화)이라는 메뉴에서 문서를 여러 가지 언어 버전으로 작성하는 방법에 대해서 설명하고 있습니다.
마크 다운 문서는 직접 번역해서 두 가지의 문서를 작성해야 합니다. docusaurus가 번역을 해주지는 않습니다. 이 메뉴얼은 두 가지 버전으로 페이지로 관리하는 과정을 설명합니다.

📌 How to

⚡ Setting configuration

docusaurus.config.js 파일에서 설정합니다.

영문 버전을 디폴트로 두고, ko-kr(한글)를 추가했습니다.

i18n: {
  defaultLocale: "en",
  locales: ["en", "ko-kr"],
},

themeConfig:
    ...
    items: [
      {
        to: "/",
        position: "left",
        label: "Documentation",
      },
		...
}

⚡ Init

아래의 명령어를 사용해서 ko-kr 지역에서 사용할 JSON 번역 파일을 초기화 해줍니다.

yarn run write-translations -- --locale ko-kr

명령어를 실행하고 나면, 아래와 같은 문서가 생성되었음을 알려줍니다.

프로젝트 파일을 살펴보면 디렉토리가 생성된 것을 확인할 수 있습니다. blog나 src/pages가 있다면 해당 디렉토리들도 생성됩니다.

git bash에서 프로젝트의 폴더에서 아래의 명령어를 사용해서 번역할 마크다운 파일을 ko-kr 디렉터리에 복사합니다.

현재 프로젝트는 docs만 필요해서 docs 명령만 실행했는데, 만약 blog나 page도 필요하다면 아래의 명령어를 모두 실행합니다.

# docs
mkdir -p i18n/ko-kr/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/ko-kr/docusaurus-plugin-content-docs/current

# blog
mkdir -p i18n/ko-kr/docusaurus-plugin-content-blog
cp -r blog/** i18n/ko-kr/docusaurus-plugin-content-blog

# src/pages
mkdir -p i18n/ko-kr/docusaurus-plugin-content-pages
cp -r src/pages/**.md i18n/ko-kr/docusaurus-plugin-content-pages
cp -r src/pages/**.mdx i18n/ko-kr/docusaurus-plugin-content-pages

⚡ 파일 번역하기

i18n/ko-kr/docusaurus-plugin-content-docs 디렉토리에 current라는 이름의 폴더 안에 모든 docs가 복사되어 있습니다.

들어있는 파일을 전부 번역한 후, 실행해봅니다. 명령어를 사용해서 한국어 버전 사이트를 확인할 수 있습니다.
ko-kr로 실행하면 ko-kr 사이트가 나오는데, 배포 전에는 버튼을 클릭해서 영문 버전으로 바꾸려고 하면 페이지를 찾을 수 없다고 나옵니다. 하지만 이는 배포 후에는 사라지니 각 명령어를 사용해서 사이트를 확인하면 됩니다.

# ko-kr version
yarn run start -- --locale ko-kr

# default version
yarn run start

⚡ 배포하기

배포 방식에는 두 가지가 있습니다. 한 가지는 단일 도메인에 배포하는 것이고 나머지는 여러 도메인에 배포하는 방식인데, 여기에서는 단일 도메인 배포를 사용했습니다.
배포 후에 확인하면 영문/한글 버전이 잘 돌아가는 것을 확인할 수 있었습니다.

yarn run build

---

⚡ 번역한 화면 URL 편집하기

이 옵션을 설정하지 않으면, ko-kr 페이지에서 편집하기 버튼을 클릭했을 때 default 페이지로 연결됩니다. 언어에 맞는 편집 페이지로 가려면 editLocalizedFiles 옵션을 설정합니다.
docusaurus.config.js 파일에서 preset 부분에 추가합니다. editLocalizedFiles: true로 설정합니다.

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',
          breadcrumbs: true,
          editUrl: ({versionDocsDirPath, docPath}) =>
            `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`,
          editLocalizedFiles: true,
	...

---

참조

https://docusaurus.io/ko/docs/i18n/introduction
https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#ex-config