1.9.x

Translate

Translations & Localization

도큐사우르스에서는 Crowdin를 사용해 번역 기능을 쉽게 추가할 수 있습니다. 영어로 작성된 문서가 작성되면 커뮤니티 기반으로 사용자가 직접 번역할 수 있는 Crowdin으로 업데이트됩니다. 영어 문자열로 작성된 최상위 페이지에서 번역할 대상 문자열은 <translate> 태그로 감싸지고 태그 안의 문자열은 번역될 수 있습니다. 다른 제목이나 라벨도 발견되면 적절하게 번역될 수 있습니다.

도큐사우르스에서 번역 관련 설정하기

도큐사우르스에서 번역을 위한 예제 파일을 만들기 위해서는 examples 스크립트를 translations 인자와 함께 실행합니다.

npm run examples translations

또는

yarn examples translations

스크립트가 실행되면 다음 파일이 생성됩니다.

pages/en/help-with-translations.js
languages.js
../crowdin.yaml
  • pages/en/help-with-translations.js 파일은 examples 스크립트가 실행되면서 생성된 것과 같은 내용으로 생성됩니다. 하지만 여기에는 translation 태그가 추가되어 있습니다.

help-with-translations.js 파일을 번역작업을 위한 가이드로 활용할 수 있습니다. 하지만 실제 저장소에 커밋할 필요는 없습니다 (파일을 삭제해도 괜찮습니다). 하지만, 도움말 페이지가 필요하고 다른 문서가 없다면 파일명을 help.js으로 바꾸어서 사용할 수도 있습니다.

  • languages.js 파일에서는 여러분의 사이트를 어떤 언어로 번역하고자 하는지를 설정합니다. 기본값으로 영어는 활성화되어있습니다.

  • crowdin.yaml 파일은 Crowdin 서비스 설정을 위해 사용하며 도큐사우르스 프로젝트 저장소에 복사됩니다. 여러분의 도큐사우르스 프로젝트의 위치가 /project/website이라면 crowdin.yaml 파일은 /project/crowdin.yaml 위치에 복사됩니다.

기존 문서 번역하기

번역 작업을 위해 여러분의 문서 파일(예를 들어 docs 디렉토리에 있는 .md 파일들)의 위치를 옮길 필요는 없습니다. 파일들은 번역작업을 위해 Crowdin 서비스로 업로드됩니다.

페이지 번역하기

페이지는 레이아웃을 변경하거나 인덱스 페이지나 도움말 페이지처럼 페이지 내 콘텐츠를 수정할 수 있습니다.

텍스트를 가지고 있는 페이지를 번역하고 싶다면 website/pages/en 디렉토리에 위치시켜야 합니다.

번역하고자 하는 문자열은 <translate> 태그로 감싸고 파일 상단에 require 상태를 추가해주어야 합니다.

...
const translate = require('../../server/translate.js').translate;
...
<h2>
  <translate>This header will be translated</translate>
</h2>
...

문자열을 어떻게 번역해야 하는지 추가 정보를 제공하기 위해 옵션 항목으로 설명을 추가할 수도 있습니다.

<p>
  <translate desc="flower, not verb">Rose</translate>
<p>

<translate> 태그는 일반 문자열인 경우에는 적절하게 동작합니다. If you have a string like "Docusaurus currently provides support to help your website use translations", wrapping the <translation> tag around that entire string will cause issues because of the markdown linking, etc. 이런 경우에는 번역하지 않을 문자열을 지정하거나 문자열 사이에 번역할 대상만 <translate> 태그로 지정하는 방법을 사용할 수 있습니다.

번역할 문자열 수집하기

지역화된 페이지 내의 문자열은 추출되어 Crowdin에 제공되어야 합니다.

website/package.json 파일에 다음과 같은 스크립트를 추가합니다.

{
  ...
  "scripts": {
    "write-translations": "docusaurus-write-translations"
  },
  ...
}

스크립트를 실행하면 영어에서 다른 문자열로 번역해야 하는 모든 문자열이 포함된 website/i18n/en.json 파일이 생성됩니다.

스크립트에는 다음과 같은 항목에서 뽑아낸 텍스트가 포함됩니다.

  • 문서의 마크다운 헤더에 있는 title, sidebar_label 문자열
  • sidebars.json에 포함된 카테고리 이름
  • siteConfig.js 파일에 있는 문구
  • siteConfig.js 파일에 있는 헤더 링크 항목의 label 문자열
  • pages 디렉토리에 있는 .js 파일 내에서 <translate> 태그로 감싼 문자열

추가로 번역할 문자열

스크립트를 실행해서 website/i18n/en.json 파일에 만들어진 문자열에 다른 항목을 추가하거나 생성된 문자열을 수정하고자 하는 경우에는 website/data/custom-translation-strings.json 파일을 추가할 수 있습니다. 이 파일은 아래와 같은 형식으로 채워집니다.

{
  "localized-strings": {
    "docs": {
      "id": {
        "title": "string1",
        "sidebar_label": "string2"
      },
      "version-0.0.1-id": {
        "title": "string3",
        "sidebar_label": "string4"
      }
    }
  },
  "pages-strings": {
    "id3": "string3",
    "id4": "string4"
  }
}

localized-strings 항목의 문자열은 문서 내 콘텐츠에 포함된 문자열이고 pages-strings 항목의 문자열은 문서 내 메타데이터(타이틀, 링크 등)를 처리합니다.

아래 예제를 참고하세요.

{
  "_comment": "This file is used to provide custom strings for translations, including overriding defaults",
  "localized-strings": {
    "translation": "Translations and Localization"
  },
  "pages-strings": {
    "Help Translate|recruit community translators for your project": "Help Us Translate"
  }
}

예제로 제공되는 생성된 website/i18n/en.json 파일을 참고하세요.

어떻게 문자열이 번역되는가

Docusaurus itself does not do any translation from one language to another. Instead, it integrates Crowdin to upload translations and then downloads the appropriately translated files from Crowdin.

도큐사우르스에서는 어떻게 번역된 문자열을 사용하는가

This section provides context about how translations in Docusaurus works.

Strings

A Docusaurus site has many strings used throughout it that require localization. However, maintaining a list of strings used through out a site can be laborious. Docusaurus simplifies this by centralizing strings.

The header navigation, for example can have links to 'Home' or your 'Blog'. This and other strings found in the headers and sidebars of pages are extracted and placed into i18n/en.json. When your files are translated, say into Spanish, a i18n/es-ES.json file will be downloaded from Crowdin. Then, when the Spanish pages are generated, Docusaurus will replace the English version of corresponding strings with translated strings from the corresponding localized strings file (e.g. In a Spanish enabled site 'Help' will become 'Ayuda').

Markdown Files

For documentation files themselves, translated versions of these files are downloaded and then rendered through the proper layout template.

Other Pages

For other pages, Docusaurus will automatically transform all <translate> tags it finds into function calls that return the translated strings from the corresponding localized file locale.json.

Crowdin

Crowdin is a company that provides translation services. For Open Source projects, Crowdin provides free string translations.

Create your translation project on Crowdin. You can use Crowdin's guides to learn more about the translations work flow. We suggest that you deselect and do not include "English" as a translatable language to prevent the creation of en-US localization files as this can lead to confusion.

Crowdin 설정에서 "Duplicate Strings" 항목은 "Hide - all duplicates will share the same translation"으로 설정합니다. 이렇게 설정하면 다른 버전의 문서에서 같은 문자열은 하나의 번역을 사용하도록 할 수 있습니다.

Your project will need a crowdin.yaml file generated. If you ran yarn examples translations or npm run examples translations, this file was created for you on the same level as your website directory.

crowdin을 콘솔창에서 설치하기를 원할 수도 있다. 이런 경우에는 설치 가이드를 참고하세요.

The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
api_key_env: CROWDIN_DOCUSAURUS_API_KEY
base_path: './'
preserve_hierarchy: true

files:

  - source: '/docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: &anchor
      locale:
        'de': 'de'
        'es-ES': 'es-ES'
        'fr': 'fr'
        'ja': 'ja'
        'ko': 'ko'
        'mr': 'mr-IN'
        'pt-BR': 'pt-BR'
        'zh-CN': 'zh-CN'
        'zh-TW': 'zh-TW'

You can go here to learn more about customizing your crowdin.yaml file.

Setup the Crowdin Scripts

You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

You can add the following to your package.json to manually trigger Crowdin.

"scripts": {
  "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
  "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
},

Manual File Sync

You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download

YOUR_CROWDIN_PROJECT_ID 항목은 Crowdin 프로젝트 이름을 설정합니다. 예를 들어 https://crowdin.com/project/docusaurus/ Url에서 docusaurus 문자열을 설정합니다. YOUR_CROWDIN_API_KEY 항목은 비밀번호와 같은 유일한 키값을 지정합니다. Crowdin 프로젝트 Settings 항목 중 API 탭에서 찾을 수 있습니다.

명령행을 실행하기 위해서는 환경변수에서 Crowdin 프로젝트 id와 api 키값(CROWDIN_PROJECT_ID, CROWDIN_API_KEY) 을 설정해주어야 합니다. 위에서처럼 인라인 명령행에 설정값을 추가할 수도 있고 .bashrc 또는 .bash_profile 파일에 추가할 수도 있습니다.

여러분의 컴퓨터에서 하나 이상의 도큐사우르스 프로젝트 지역화를 처리하고자 한다면 환경변수의 이름을 구분할 수 있는 고유한 값으로 변경해주어야 합니다(CROWDIN_PROJECTNAME_PROJECT_ID, CROWDIN_PROJECTNAME_API_KEY).

파일들이 생성되고 나면 website/i18n 또는 website/translated_docs 디렉토리에 파일을 가지고 있을 필요가 없습니다. website/i18n/*와 website/translated_docs에 .gitignore 파일을 추가해줍니다.

Automated File Sync Using CircleCI

You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

먼저 여러분의 프로젝트 디렉토리에서 .circleci/config.yml 파일을 열고 번역할 영어 파일을 업로드하고 번역된 파일을 Crowdin CLI를 사용해 내려받을 수 있는 단계를 포함하도록 업데이트합니다. .circleci/config.yml 파일 예제는 아래를 참고하세요.

# If you only want circle to run on direct commits to master, you can uncomment this out
# and uncomment the filters: *filter-only-master down below too
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # specify the version you desire here

      - image: circleci/node:8.11.1

    steps:

      - checkout
      - run:
          name: Deploying to GitHub Pages
          command: |
            git config --global user.email "<GITHUB_USERNAME>@users.noreply.github.com"
            git config --global user.name "<YOUR_NAME>"
            echo "machine github.com login <GITHUB_USERNAME> password $GITHUB_TOKEN" > ~/.netrc
            # install Docusaurus and generate file of English strings
            - cd website && yarn install && yarn run write-translations && cd ..
            # crowdin install
            - sudo apt-get install default-jre
            - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
            - sudo dpkg -i crowdin.deb
            # translations upload/download
            - crowdin --config crowdin.yaml upload sources --auto-update -b master
            - crowdin --config crowdin.yaml download -b master
            # build and publish website
            cd website && GIT_USER=<GIT_USER> yarn run publish-gh-pages

workflows:
  version: 2
  build_and_deploy:
    jobs:

      - deploy-website:
#         filters: *filter-only-master

The crowdin command uses the crowdin.yaml file generated with the examples script. It should be placed in your project directory to configure how and what files are uploaded/downloaded.

Note that in the crowdin.yaml file, CROWDIN_PROJECT_ID and CROWDIN_API_KEY are environment variables set-up in Circle for your Crowdin project. They can be found in your Crowdin project settings.

Now, Circle will help you automatically get translations prior to building your website. The provided crowdin.yaml file will copy translated documents into website/translated_docs/, and translated versions of the i18n/en.json strings file will into i18n/${language}.json.

If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

이미 번역된 문서 번역하기

If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

  -
    source: '/website/versioned_docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: *anchor

Translated, versioned documents will be copied into website/translated_docs/${language}/${version}/.

← Navigation and SidebarsVersioning →