MDX와 코드는 그대로 두고 Docusaurus 문서를 다른 언어로 번역
docs 폴더를 ZIP으로 압축해 업로드하면, 번역이 완료되어 i18n/<locale>/docusaurus-plugin-content-docs/current에 바로 넣을 수 있는 동일한 파일들이 다운로드됩니다. import 구문, Tabs 등 컴포넌트, admonition 마커, 코드 블록, 링크는 원본 그대로 유지되며 제목, 사이드바 라벨, 설명(description), 본문 텍스트만 번역됩니다. 회원가입 없이 첫 부분 무료이며, 최대 1,000,000자 텍스트 기준 $5 1회 결제입니다.
복사-붙여넣기 없는 Docusaurus i18n 다국어 지원
Docusaurus는 로케일 폴더 내에 원본과 동일한 파일명으로 번역된 모든 문서를 요구합니다. 이를 수작업으로 처리하거나 AI 챗봇에 파일별로 넣으면 속도가 느릴 뿐만 아니라, MDX 환경에서는 import명이 번역되거나 prop이 바뀌어 빌드가 깨지는 심각한 문제가 발생합니다. 본 도구는 독자에게 보이는 부분만 번역하고 나머지는 원본 파일에서 그대로 가져옵니다.
인라인 코드, 링크 타깃, 이미지 경로, MDX {expressions} 등은 번역 전에 마커로 치환된 뒤 번역 후 복원되므로 번역 모델에 노출되지 않습니다. <Tabs>나 <TabItem value="mac"> 같은 순수 JSX 줄은 건너뜁니다. 코드 블록은 주석을 포함해 통째로 번역에서 제외됩니다.
다운로드 후 진행 방법
- 압축을 풀고 docs-<locale> 폴더 내용을 i18n/<locale>/docusaurus-plugin-content-docs/current 경로에 복사합니다
- JSON 형식으로 관리되는 테마 라벨 및 사이드바 카테고리 이름을 번역하려면 docusaurus write-translations 명령어를 실행합니다
- --locale <locale> 옵션으로 사이트를 실행하고 정상 작동을 확인합니다
- 경고 파일(warnings)이 생성되었다면 안내된 단락을 확인하고 수정합니다
포함되지 않는 항목
사이드바 카테고리 라벨, 내비게이션 바, 푸터 텍스트는 write-translations로 생성되는 JSON 파일에 저장되므로, 해당 항목은 현지화 파일 번역 도구를 이용해 번역하세요. 블로그 글도 문서와 동일한 방식으로 처리됩니다. blog 폴더를 ZIP으로 압축해 별도 작업으로 업로드하거나 docs와 함께 하나의 .zip으로 묶어 업로드하시면 됩니다.
도구의 작동 방식, 비용, 파일 처리 방식은 Markdown 문서 번역 페이지에서, 모든 도구의 가격은 요금제 페이지에서 확인하세요.
최종 업데이트
자주 묻는 질문
빌드가 오류 없이 통과하나요?
MDX 빌드 실패의 주요 원인인 import, 컴포넌트, props, 코드, 링크 타깃을 원본 파일에서 그대로 복사합니다. 파일을 복사한 뒤 빌드를 한 번 실행하고, warnings 파일이 있다면 확인해 주세요.
Admonition 콜아웃도 번역되나요?
:::note 및 ::: 같은 마커 행은 그대로 유지되며, 그 내부의 텍스트만 번역됩니다.
한 작업당 최대 처리 용량은 얼마인가요?
$5 결제 시 최대 1,000,000자(약 300페이지 분량)의 텍스트를 처리할 수 있습니다. 코드 블록과 프론트매터 키는 글자 수에 포함되지 않습니다.
일부 파일만 먼저 테스트해 볼 수 있나요?
네. 첫 부분 무료 번역되어 화면에 표시되며, 최대 40개 단락 분량의 작업은 전체 무료입니다.