Skip to main content
버전: 3.9.2

i18n - 소개

It is easy to translate a Docusaurus website with its internationalization (i18n) support.

목표​

It is important to understand the design decisions behind the Docusaurus i18n support.

For more context, you can read the initial RFC and PR.

i18n의 목표​

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

  • Simple: just put the translated files in the correct filesystem location
  • 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
  • Low-overhead runtime: documentation is mostly static and does not require heavy JS libraries or polyfills
  • Scalable build-times: allow building and deploying localized sites independently
  • Localize assets: an image of your site might contain text that should be translated
  • No coupling: not forced to use any SaaS, yet integrations are possible
  • Easy to use with Crowdin: a lot of Docusaurus v1 sites use Crowdin and should be able to migrate to 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 설계 시 고려하지 않은 부분​

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

  • Automatic locale detection: opinionated, and best done on the server (your hosting provider)
  • Translation SaaS software: you are responsible to understand the external tools of your choice
  • Translation of slugs: technically complicated, little SEO value

번역 절차​

개요​

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

  1. Configure: declare the default locale and alternative locales in docusaurus.config.js
  2. Translate: put the translation files at the correct filesystem location
  3. Deploy: build and deploy your site using a single or multi-domain strategy

번역 파일​

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

마크다운 파일​

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

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

JSON 파일​

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

  • Your React code: standalone React pages in src/pages, or other components
  • Layout labels provided through themeConfig: navbar, footer
  • 플러그인 옵션을 통해 제공되는 레이아웃 라벨: 문서 사이드바 카테고리 라벨, 블로그 사이드바 타이틀 등

The JSON format used is called Chrome i18n:

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

데이터 파일​

일부 플러그인은 전체적으로 현지화된 외부 데이터 파일에서 읽을 수 있습니다. 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.

번역 파일 위치​

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

Each locale and plugin has its own i18n subfolder:

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

For multi-instance plugins, the path is 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   # 메뉴바 테마 구성의 텍스트 라벨

The JSON files are initialized with the docusaurus write-translations CLI command. 각 플러그인은 해당 폴더에서 자체 번역 콘텐츠를 가져오며, code.json 파일은 리액트 코드에 사용되는 모든 텍스트 레이블을 정의합니다.

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