다국어 사이트
이 페이지에서는 번역된 도큐사우루스 v1 사이트를 도큐사우루스 v2로 이전하는 방법을 설명합니다.
i18n 기능 차이
도큐사우루스 v2 i18n은 몇 가지 차이를 제외하면 도큐사우루스 v2 i18n과 개념적으로는 거의 비슷합니다.
크라우드인(Crowdin) 서비스에 종속되어 있지 않으며 깃이나 다른 SaaS를 사용할 수도 있습니다.
다른 파일시스템 경로
도큐사우루스 v2에서 번역된 콘텐츠는 website/i18n/[locale] 경로에서 찾을 수 있습니다.
도큐사우루스 v2는 플러그인 시스템을 기반으로 하는 모듈 형태로 동작하며 각 플러그인은 자체적으로 번역을 관리합니다.
때문에 각 플러그인은 website/i18n/fr/docusaurus-plugin-content-blog처럼 i18n 하위 디렉터리를 가지고 있습니다.
translation API 업데이트
도큐사우루스 v1에서는 페이지 번역 시 <translate> 태그를 사용했습니다.
const translate = require('../../server/translate.js').translate;
<h2>
<translate desc="the header description">
This header will be translated
</translate>
</h2>;
도큐사우루스 v2에서는 <Translate> 태그를 사용합니다.
import Translate from '@docusaurus/Translate';
<h2>
<Translate id="header.translation.id" description="the header description">
This header will be translated
</Translate>
</h2>;
여러분의 코드에서 번역 대상을 추출할 때는 write-translations CLI를 계속 사용할 수 있습니다.
코드 번역 작업은 크롬 i18n JSON 형식을 사용해 이제는 i18n/[locale]/code.json에 추가됩니다.
좀 더 엄격한 마크다운 구문 분석
도큐사우루스 v2는 마크다운 파일 구문 분석을 위해 MDX를 사용합니다.
MDX는 마크다운 파일을 리액트 컴포넌트로 컴파일합니다. 도큐사우루스 v1 파서보다 좀 더 엄격한 규칙을 따릅니다. 때문에 잘못된 콘텐츠가 표시되는 대신 빌드 실패가 발생합니다.
또한 HTML 요소는 JSX 요소로 바꾸어주어야 합니다.
번역 대상이 크라우드인에 적합하지 않거나 유효하지 않는 마크업을 사용했다면 v2 번역 사이트 빌드에 실패할 수 있기 때문에 i18n 작업 시 유효성을 좀 더 중요하게 확인해야 합니다. 오류를 수정하기 위해 일부 번역 대상을 검토해야 할 수도 있습니다.
마이그레이션 전략
v2로 번역 파일을 이전한 후에도 기존 v1 파일을 유지하는 방법을 설명합니다.
크라우드인을 사용해 도큐사우루스 v1 사이트를 이전하기 위한 여러가지 사용할 수 있는 전략이 있으며 각각은 장단점을 가지고 있습니다.
이 문서는 여러분이 문서 이전 시 최선의 방법을 선택할 수 있도록 작성했습니다. 더 좋은 방법이 있다면 언제든지 알려주세요!
다음 방법을 우선적으로 권장합니다.
- 번역 없이 도큐사우루스 v1 사이트를 v2로 이전합니다.
- 도큐사우루스 v2의 새로운 i18n 시스템을 자세히 살펴봅니다.
- 번역되지 않는 크라우드인 프로젝트를 새로 만들어서 v2 사이트를 위한 크라우드인 작업을 진행합니다. 자세한 내용은 크라우드인 튜토리얼 문서를 참고하세요.
크라우드인과 도큐사우루스 v2 i18n에 대한 이해 없이 이전을 시도하지는 말아주세요.
새로운 크라우드인 프로젝트 만들기
운영하고 있는 v1 사이트가 손상되는 것을 피하기 위한 방법 중 하나는 기존 v1 크라우드인 프로젝트를 그대로 복제하는 겁니다.
이 전략은 제스트(Jest) 웹 사이트 업그레이드 시에도 사용했습니다.
아쉽게도 크라우드인은 "프로젝트 사본 만들기나 복제하기" 기능이 없습니다. 때 문에 좀 작업이 복잡해집니다.
- 기존 프로젝트에서
.tmx확장자를 가지는 번역 메모리 파일을 내려받습니다. (https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm>View Records) - 번역 메모리 파일을 새로운 프로젝트에 업로드합니다. (
https://crowdin.com/project/<NEW_PROJECT>/settings#tm>View Records) - i18n 문서에 맞게 도큐사우루스 v2를 위한
crowdin.yml파일을 재설정합니다. - 도큐사우루스 v2 소스 파일을 크라우드인 CLI를 사용해 새로운 프로젝트에 업로드합니다.
id나slug같이 번역하지 않아야 하는 문자열은 크라우드인에서 "hidden string"으로 설정합니다.- "Translations" 탭에서 "Pre-Translation > via TM"을 클릭합니다.(
https://crowdin.com/project/<NEW_PROJECT>/settings#translations) - "100% match"("Perfect" 옵션보다 좀 더 많은 콘텐츠가 번역 처리됩니다) 항목을 선택해 소스를 사전 번역합니다.
- 크라우드인 번역 파일을 로컬에 내려받습니다.
- 여러분의 사이트를 실행하고 빌드합니다. 그리고 다른 에러는 없는지 확인합니다.
첫 번째 시도에서는 에러가 발생할 수 있습니다. 사전 번역에서 번역하지 않아야 하는 항목(프런트 매터, 권고사항, 코드 블록 등)을 번역하거나 번역된 MD 파일이 MDX 구문 분석에서 유효하지 않은 것으로 처리될 수 있습니다.
사이트 빌드가 성공할 때까지 에러를 수정해주어야 합니다. 번역된 MD 파일을 로컬에서 수정하고 docusaurus build --locale fr 명령을 사용해 해당 로케일에서 발생하는 에러를 수정합니다.
에러를 수정하는 가이드가 따 로 있지는 않습니다. 하지만 공통적으로 발생하는 에러는 다음과 같습니다.
- 크라우드인에서 "hidden strings"을 적절하게 체크하지 않으면 사전 번역 시 번역하지 않아야 할 문자열이 번역될 수 있습니다.
- v1 번역이 잘못되어 v2에서 유효하지 않은 마크업 에러가 발생합니다. 번역 내 잘못된 HTML 요소가 있거나 닫히지 않은 태그로 인해 발생합니다.
- JSX 요소 대신 HTML 요소를 사용해 MDX 파서에서 거절될 수 있습니다(MDX playground에서 디버깅해볼 수 있습니다).
사전 번역 과정을 반복하고나서 마지막에는 "Perfect" 옵션을 사용해 일부 언어/파일을 대상으로 사전 번역을 시도합니다.
문제가 발생한 마크다운 요소 주변에 mdx-code-block을 사용하면 크라우드인에서 코드 블록을 훼손할 가능성을 줄여줍니다.
이전 프로젝트에서는 번역되었지만 새로운 프로젝트에서 번역되지 않는 항목이 있을 수 있습니다.
크라우드인 마크다운 파서도 업데이트되고 있어서 크라우드인 프로젝트에서 사용하는 파서 버전이 다를 수 있습니다. 때문에 모든 문자열에 대한 사전 번역 처리가 되지 않을 수 있습니다.
파서 버전에 대한 정보는 별도 제공되지 않습니다. 필요하다면 크라우드인 지원팀에 연락해 여러분의 프로젝트에서 사용하는 파서 정보를 확인하고 버전에 따라 수정할 수 있습니다.
같은 CLI 버전과 파서 버전을 사용하는 크라우드인 프로젝트라면 좀 더 좋은 결과를 만들 수 있습니다.
크라우드인은 "upload translations" 기능을 지원합니다. 하지만 마크다운을 사용하는 경우에는 그다지 좋은 결과가 나오지 않습니다.
기존 크라우드인 프로젝트 사용하기
기존 크라우드인 프로젝트를 수정해도 큰 문제가 없다면 크라우드인 브랜치 시스템을 사용할 수 있습니다.
이 방법은 아직 테스트해보지 못했습니다. 적용해보시고 피드백을 부탁드립니다.
이 방법을 사용하면 새로운 크라우드인 프로젝트를 만들고 번역 메모리를 전송하고 사전 번역을 처리하고 사전 번역에서 발생한 오류를 체크할 필요가 없습니다.
도큐사우루스 v2를 위한 크라우드인 브랜치를 만들고 v2 소스를 업로드한 후 크라우드인 브랜치를 main에 병합하기만 하면 됩니다.
크라우드인 대신 깃 사용하기
크라우드인에서 이전 작업을 하지 않고 번역 파일을 깃에 추가하는 방법도 있습니다.
Crowdin CLI를 사용해 v1 번역 파일을 내려받고 도큐사우루스 v2 파일시스템에 적절한 위치에 번역 파일을 가져다놓습니다.