메인 컨텐츠로 이동
버전: Canary 🚧

i18n - 소개

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

목표​

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

좀 더 자세한 내용은 RFC와 PR를 참고하세요.

i18n의 목표​

도큐사우루스 i18n 시스템의 목표는 아래와 같습니다.

  • 단순함: 정확한 파일 시스템 위치에 번역된 파일을 가져다놓기만 하면 됩니다.
  • 유연한 번역 워크플로우: 깃(단일 저장소, 포크 또는 서브모듈), SaaS 소프트웨어, FTP를 사용할 수 있습니다.
  • 유연한 배포 옵션: 단일, 멀티 도메인 또는 두 가지를 같이 적용할 수 있습니다.
  • 모듈화: 플러그인 개발자에게 i18n을 지원하도록 허용합니다.
  • 최소한의 자원으로 실행: 대부분 정적인 파일로 문서를 만들며 무거운 자바스크립트 라이브러리나 추가 기능을 필요로 하지 않습니다.
  • 확장성 있는 빌드: 로케일 사이트를 독립적으로 빌드하고 배포할 수 있어야 합니다.
  • 애셋 번역: 사이트에 게시된 이미지에 포함된 텍스트도 번역할 수 있어야 합니다.
  • 유연한 결합: 특정 SaaS를 통합할 수 있어야 하지만 사용하도록 강제되지 않아야 합니다.
  • 크라우드인(Crowdin) 사용 편의성: 도큐사우루스 v1에서 번역한 항목을 v2로 가져갈 수 있어야 합니다.
  • 기본적인 SEO 지원: hreflang 같은 유용한 SEO 헤더 설정이 제공되어야 합니다.
  • RTL 지원: 오른쪽에서 왼쪽으로 읽는 로케일(아랍어, 히브리어 등)을 지원하고 쉽게 구현할 수 있어야 합니다.
  • 기본 번역: 클래식 테마에서 제공하는 라벨은 다양한 언어로 기본 번역되어 제공되어야 합니다

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

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

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

번역 절차​

개요​

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

  1. 설정: docusaurus.config.js에서 기본 로케일과 대체 로케일을 설정합니다.
  2. 번역: 정확한 파일 시스템 위치에 번역된 파일을 가져다놓기만 하면 됩니다.
  3. 배포: 단일 또는 멀티 도메인 전략에 따라 여러분의 사이트를 빌드하고 배포합니다.

번역 파일​

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

마크다운 파일​

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

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

JSON 파일​

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

  • 리액트 코드: src/pages에 있는 독립형 리액트 페이지 또는 다른 컴포넌트
  • themeConfig을 통해 제공되는 레이아웃 라벨: navbar, footer
  • 플러그인 옵션을 통해 제공되는 레이아웃 라벨: 문서 사이드바 카테고리 라벨, 블로그 사이드바 타이틀 등

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/[locale]/docusaurus-plugin-content-blog/authors.yml 아래에 사본을 만들어 번역할 수 있는 authors.yml 파일을 사용합니다.

번역 파일 위치​

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

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

website/i18n/[locale]/[pluginName]/...
참고

멀티 인스턴스 플러그인의 경우에는 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 # classic 테마에 필요한 번역 데이터
        ├── footer.json   # 바닥글 테마 구성의 텍스트 라벨
        └── navbar.json   # 메뉴바 테마 구성의 텍스트 라벨

JSON 파일은 docusaurus write-translations 명령으로 초기화됩니다. Each plugin sources its own translated content under the corresponding folder, while the code.json file defines all text labels used in the React code.

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