Version: 2.0.0-beta.5 🚧

i18n - 소개

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

목표#

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

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

i18n의 목표#

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

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

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

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

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

번역 절차#

개요#

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

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

번역 파일#

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

마크다운 파일#

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

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

상세설명(Description) 속성: 번역 작업자를 위한 설명을 추가할 수 있습니다.
다양한 외부 도구 지원: 크롬 확장 기능, 크라우드인(Crowdin), 트랜시펙스(Transifex), Phrase, Applanga

번역 파일 위치#

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

각 로케일과 플러그인을 위한 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 파일을 사용해 문서 버전 기능을 적용한 번역을 지원합니다.

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