Skip to main content
Version: 2.0.0-beta.0

i18n - 소개

국제화 기능(i18n) 지원으로 도큐사우루스 웹 사이트 번역 작업이 좀 더 간단해졌습니다.

목표#

먼저 도큐사우루스의 i18n 지원 배경이 되는 디자인 의사결정을 이해하는 것이 중요합니다.

좀 더 자세한 내용은 RFCPR를 참고하세요.

i18n의 목표#

The goals of the Docusaurus i18n system are:

  • 단순함: 정확한 파일 시스템 위치에 번역된 파일을 가져다놓기만 하면 됩니다.
  • Flexible translation workflows: use Git (monorepo, forks, or submodules), SaaS software, FTP
  • Flexible deployment options: single, multiple domains, or hybrid
  • Modular: allow plugin authors to provide i18n support
  • 최소한의 자원으로 실행: 대부분 정적인 파일로 문서를 만들며 무거운 자바스크립트 라이브러리나 추가 기능을 필요로 하지 않습니다.
  • Scalable build-times: allow building and deploying localized sites independently
  • 애셋 번역: 사이트에 게시된 이미지에 포함된 텍스트도 번역할 수 있어야 합니다.
  • No coupling: not forced to use any SaaS, yet integrations are possible
  • 크라우드인(Crowdin) 사용 편의성: 도큐사우루스 v1에서 번역한 항목을 v2로 가져갈 수 있어야 합니다.
  • Good SEO defaults: we set useful SEO headers like hreflang for you
  • RTL support: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
  • Default translations: classic theme labels are translated for you in many languages

i18n 설계 시 고려하지 않은 부분#

아래 항목은 지원하지 않습니다.

  • 자동 로케일 탐지: 이미 서버에서 잘 하고 있는 기능입니다.
  • SaaS형 번역 소프트웨어: 외부 도구를 선택했다면 그건 여러분의 책임입니다.
  • 슬러그(slug) 번역: 기술적으로 복잡하고 SEO에 큰 도움을 주지 않습니다.

번역 절차#

개요#

번역한 도큐사우루스 웹 사이트를 만드는 절차를 살펴봅니다.

  1. Configure: declare the default locale and alternative locales in docusaurus.config.js
  2. 번역: 정확한 파일 시스템 위치에 번역된 파일을 가져다놓기만 하면 됩니다.
  3. Deploy: build and deploy your site using a single or multi-domain strategy

번역 파일#

여러분은 두 가지 종류의 번역 파일 작업이 필요합니다.

마크다운 파일#

여러분의 도큐사우루스 웹 사이트의 중심이 되는 콘텐츠입니다.

마크다운과 MDX 문서는 각 단락을 개별적인 문자열로 잘라주긴 하지만 전체 콘텐츠를 유지하기 위해서는 모두 번역해야 합니다.

JSON 파일#

번역 시 사용하는 JSON 파일은 아래와 같습니다.

  • 리액트 코드: <Translate> 컴포넌트를 사용한 경우
  • 테마: 메뉴바, 푸터
  • 플러그인: 사이드바에 표시되는 텍스트

Chrome i18n이라고 불리는 JSON 형식을 사용합니다.

{
"myTranslationKey1": {
"message": "Translated message 1",
"description": "myTranslationKey1 is used on the homepage"
},
"myTranslationKey2": {
"message": "Translated message 2",
"description": "myTranslationKey2 is used on the FAQ page"
}
}

아래 2가지 이유로 해당 JSON 형식을 사용합니다.

번역 파일 위치#

번역 파일은 적절한 파일시스템 경로에 만들어져야 합니다.

각 로케일과 플러그인을 위한 i18n 하위 디렉터리가 있습니다.

website/i18n/<locale>/<pluginName>/...
note

멀티 인스턴스 플러그인의 경우에는 website/i18n/<locale>/<pluginName>-<pluginId>/... 형식의 경로를 사용합니다.

프랑스어로 번역된 간단한 도큐사우루스 사이트는 아래와 같은 구조로 만들어집니다.

website/i18n
└── fr
├── code.json
├── docusaurus-plugin-content-blog
│   └── 2020-01-01-hello.md
├── docusaurus-plugin-content-docs
│   ├── current #
│   │   ├── doc1.md
│   │   └── doc2.mdx
│   └── current.json
└── docusaurus-theme-classic
├── footer.json
└── navbar.json

JSON 파일은 docusaurus write-translations 명령으로 초기화됩니다.

code.json 파일은 <Translate> API를 사용해서 리액트 컴포넌트로부터 추출합니다.

info

docusaurus-plugin-content-docs 플러그인은 current 디렉터리와 current.json 파일을 사용해 문서 버전 기능을 적용한 번역을 지원합니다.

사용하는 플러그인이나 테마에 따라 번역 파일 위치를 각각 지정할 수 있습니다.