메인 컨텐츠로 이동
Version: 2.0.0-beta.16 🚧

i18n - 소개

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

목표

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

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

i18n의 목표

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

  • 단순함: 정확한 파일 시스템 위치에 번역된 파일을 가져다놓기만 하면 됩니다.
  • 유연한 번역 워크플로우: 깃(단일 저장소, 포크 또는 서브모듈), SaaS 소프트웨어, FTP를 사용할 수 있습니다.
  • 유연한 배포 옵션: 단일, 멀티 도메인 또는 두 가지를 같이 적용할 수 있습니다.
  • 모듈화: 플러그인 개발자에게 i18n을 지원하도록 허용합니다.
  • Low-overhead runtime: documentation is mostly static and does not require heavy JS libraries or polyfills
  • 확장성 있는 빌드: 로케일 사이트를 독립적으로 빌드하고 배포할 수 있어야 합니다.
  • 애셋 번역: 사이트에 게시된 이미지에 포함된 텍스트도 번역할 수 있어야 합니다.
  • 유연한 결합: 특정 SaaS를 통합할 수 있어야 하지만 사용하도록 강제되지 않아야 합니다.
  • Easy to use with Crowdin: a lot of Docusaurus v1 sites use Crowdin and should be able to migrate to v2
  • 기본적인 SEO 지원: hreflang 같은 유용한 SEO 헤더 설정이 제공되어야 합니다.
  • RTL 지원: 오른쪽에서 왼쪽으로 읽는 로케일(아랍어, 히브리어 등)을 지원하고 쉽게 구현할 수 있어야 합니다.
  • Default translations: classic theme labels are translated for you in many languages

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

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

  • Automatic locale detection: opinionated, and best done on the server (your hosting provider)
  • SaaS형 번역 소프트웨어: 외부 도구를 선택했다면 그건 여러분의 책임입니다.
  • 슬러그(slug) 번역: 기술적으로 복잡하고 SEO에 큰 도움을 주지 않습니다.

번역 절차

개요

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

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

번역 파일

You will work with three kinds of translation files.

마크다운 파일

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

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

JSON 파일

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

  • Your React code: standalone React pages in src/pages, or other components
  • Layout labels provided through themeConfig: navbar, footer
  • Layout labels provided through plugin options: docs sidebar category labels, blog sidebar title...

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 형식을 사용합니다.

Data files

Some plugins may read from external data files that are localized as a whole. For example, the blog plugin uses an authors.yml file that can be translated by creating a copy under i18n/[locale]/docusaurus-plugin-content-blog/authors.yml.

번역 파일 위치

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

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

website/i18n/[locale]/[pluginName]/...
note

For multi-instance plugins, the path is website/i18n/[locale]/[pluginName]-[pluginId]/....

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

website/i18n
└── fr
├── code.json # Any text label present in the React code
# Includes text labels from the themes' code
├── docusaurus-plugin-content-blog # translation data the blog plugin needs
│ └── 2020-01-01-hello.md

├── docusaurus-plugin-content-docs # translation data the docs plugin needs
│ ├── current
│ │ ├── doc1.md
│ │ └── doc2.mdx
│ └── current.json

└── docusaurus-theme-classic # translation data the classic theme needs
├── footer.json # Text labels in your footer theme config
└── navbar.json # Text labels in your navbar theme config

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.

Each content plugin or theme is different, and defines its own translation files location: