인포그랩은 2024년 11월 ‘Teleport 공식 기술 문서 한글판 by 인포그랩(이하 Teleport 공식 기술 문서 한글판)’을 선보였습니다. 이 서비스는 인프라 접근 관리 도구인 Teleport의 전체 기술 문서를 한글로 제공하는데요. 인포그랩은 OpenAI의 생성형 인공지능(AI) 모델 GPT로 Teleport 기술 문서 총 700여 개를 번역했습니다. Teleport의 공식 리셀러인 인포그랩은 국내 사용자가 Teleport를 더 쉽게 이해하고 편리하게 사용하도록 지원하고자 이 서비스를 만들었습니다.
저는 이번 프로젝트에서 AI 번역 로직 구현과 MDX 문법 교정 스크립트 개발 등을 담당했는데요. 제가 사내 기술 문서 번역 프로젝트에 참여한 건 ‘GitLab 공식 기술 문서 한글판 by 인포그랩’과 ‘Mattermost 공식 기술 문서 한글판 by 인포그랩’에 이어 이번이 세 번째였습니다. 이 글에서는 제가 Teleport 기술 문서를 AI로 번역하며 부딪친 난관과 이를 극복한 과정을 공유하려 합니다. Teleport 공식 기술 문서 한글판의 서비스 내용과 개발 배경은 다음 글을 참고해 주세요.
MDX 문법의 특수성
개발 후기를 본격적으로 설명하기에 앞서 Teleport 기술 문서 형식을 먼저 짚고 가겠습니다. Teleport 기술 문서는 MDX 형식인데요. MDX는 Markdown에 기반하지만 완전한 Markdown은 아닙니다. MDX는 Markdown과 구체적으로 무엇이 다를까요? MDX 문법의 특수성을 살펴보겠습니다.
MDX란?
MDX는 Markdown과 JSX(JavaScript XML)를 결합한 형식입니다. 이는 대화형 차트나 알림과 같은 컴포넌트를 가져와 콘텐츠에 포함하도록 지원하죠. 확장자는 .mdx입니다.
MDX는 일반 Markdown 파일처럼 작성할 수 있는데요. Markdown과 다른 점은 React 컴포넌트를 파일 내부에 직접 사용할 수 있다는 겁니다. 예를 들어, MDX 파일에는 React 컴포넌트를 아래와 같이 포함할 수 있는데요.
안녕하세요!
이것은 일반 Markdown 내용입니다.
<MyComponent title="MDX를 활용해보세요!">
InfoGrab의 John입니다.
</MyComponent>
위 예시에서 MyComponent는 React 컴포넌트로, MDX 파일에 위와 같이 삽입할 수 있습니다.
특수 문법
MDX를 사용하면, Admonition 또는 Notice와 같은 React 컴포넌트도 파일에 포함할 수 있습니다. Teleport 기술 문서에서 Admonition은 특정 정보를 강조하거나 경고를 표시하는 데 쓰이는데요. 이 컴포넌트는 JSX 태그 형태로 작성하죠. Admonition은 아래 와 같이 MDX 파일에 다른 Markdown 콘텐츠와 함께 사용할 수 있습니다.
<Admonition type="note">
이것은 사용 기반 요금제를 사용하는 사용자에게만 표시됩니다. 사용자는 청구 리소스를 읽을 수 있는 권한이 필요합니다.
</Admonition>
Admonition이 Teleport 기술 문서 사이트 UI에 적용된 모습
번역용 프롬프트도 일신우일신
앞서 언급했듯 MDX는 Markdown에 기반하지만 완전한 Markdown은 아닙니다. 저는 지난 프로젝트에서 RST 형식인 Mattermost 기술 문서를 번역하다 문법 특수성 문제로 고생했는데요. 이 기억을 떠올리며 ‘예전 번역 프로젝트에서 활용한 프롬프트를 이번에 그대로 재활용해선 안 된다’는 점을 상기했습니다.
따라서 MDX 형식을 고려해 역할, 특수 문법 번역 시 주의 사항, 번역 규칙, 예시를 구체적으로 담아 Teleport 기술 문서 번역용 프롬프트를 재작성했습니다. 특히 Admonition, Notice와 같은 React 컴포넌트 이름을 AI로 번역할 때, 문서가 정상적으로 빌드되지 않을 수 있는데요. 이러한 가능성을 염두에 두고 프롬프트를 신중하고 세밀하게 작성했습니다.
이를 제외하면 Teleport 기술 문서 번역은 GitLab 기술 문서 번역과 비슷한 점이 많았습니다. 이에 저는 이번 프로젝트를 빠르게 완료할 걸로 예상했고요. 실제 번역 작업은 예상보다 훨씬 더 신속히 이뤄졌습니다.
‘번역을 완료하면, 배포도 금방 하겠지’라고 생각하며 배포 작업에 들어갔는데요. 막상 작업을 수행하다 보니 예상치 못한 문제점이 수면 위로 하나둘씩 드러났습니다.
빌드 실패
저는 Teleport의 공식 리포지터리에서 코드를 클론한 다음, package.json에 명시된 다양한 명령어를 실행하며 문서 구조를 파악했습니다. 스타트와 프리뷰 등은 문제없이 작동했습니다. 그러나 배포 전 가장 중요한 작업인 빌드 과정에 문제가 생겼습니다.
빌드를 실행할 때, Teleport 기술 문서 사이트를 구성하는 코드 어딘가에서 타입 에러가 발생했습니다. 저는 개발 경험이 많지 않아 문제 원인을 정확히 파악하기가 어려웠는데요. AI에 질문하며 여러 방법으로 수정하고 빌드를 시도했지만 문제를 해결하지 못했습니다.
결국 저는 개발 경험이 풍부한 다른 DevOps 엔지니어의 도움을 받아 문제를 해결했는데요. 문제 원인은 Teleport 기술 문서 사이트에서 자체적으로 사용하는 한 컴포넌트에 있었습니다. 이 컴포넌트에서 사용하는 라이브러리가 작동하려면 시크릿 키가 필요했는데요. 이 키가 없어서 라이브러리가 제대로 작동하지 않아 에러가 생겼죠.
저는 도움을 주신 DevOps 엔지니어의 조언에 따라 관련 부분을 아래와 같이 주석 처리했고요. 이로써 빌드 문제는 해결의 실마리를 찾은 듯했습니다.
MDX 문법 깨짐
저는 이제 빌드가 정상적으로 이뤄질 줄 알았는데요. 그러나 빌드는 여전히 완료되지 않았습니다. 빌드를 다시 시도하니 아래와 같은 오류가 발생했는데요. 이 오류는 특정 경로의 문서에 문법적으로 맞지 않는 내용이 있어서 생겼습니다.
해당 문서로 이동해 상태를 직접 확인했더니 문제는 없었습니다. 이 문서는 모든 문법을 완벽하게 지켜 번역된 상태였어요. 원본과 똑같았습니다.
이에 저는 “include 하는 파일이 잘못된 게 아닐까?”라고 추측했는데요. include 하는 파일의 경로를 찾아 파일 내용을 살펴보니 MDX 문법이 조금씩 깨져 있었습니다.
저는 MDX 문법이 깨진 파일을 찾아 수정했는데요. 문제가 있는 파일을 찾는 과정은 굉장히 번거롭고 힘들었습니다. 특히 2중으로 include 하는 파일을 찾아 스크립트로 수정하는 일이 버거웠고요. 그 결과, 초반 빌드와 검수 작업에 오랜 시간이 걸렸습니다.
드디어 배포
이후에도 저는 모든 문서 페이지에서 문법이 깨지지 않도록 계속 수정했습니다. 사내 여러 멤버들과 문서를 추가 검수하고 바로잡은 결과, 모든 문서 페이지가 깨짐 없이 실행될 수 있었죠.
마지막으로 저는 GitLab에서 CI/CD 파이프라인을 구축했고요. 사내 클러스터에 Teleport 공식 기술 문서 한글판이 배포되도록 설정했습니다.
여러 우여곡절 끝에 Teleport 공식 기술 문서 한글판이 국내 사용자에게 드디어 공개됐습니다.
맺음말
저는 이번 프로젝트에서 기술 문서 리포지터리의 브랜치를 서브 모듈 형식으로 활용해 빌드를 진행했고요. 이로써 Teleport 기술 문서 원본과 동일한 방식으로 한글판을 관리하도록 설정했습니다. 그 결과, 앞으로 문서를 업데이트할 때 버전 제어를 쉽게 하고, 사용자가 특정 버전의 문서를 편리하게 찾을 수 있을 걸로 기대합니다.
인포그랩 은 AI로 GitLab, Mattermost, Teleport 등 다양한 글로벌 IT 솔루션의 기술 문서를 번역했는데요. 이러한 경험이 차곡차곡 쌓여 이제는 문서 번역 프로세스에 자동화가 정착되고 있습니다. 수동 작업 비중은 줄고 있고요. 번역용 AI 모델을 신형으로 업그레이드하며 번역 정확도를 높이고, 비용도 절감하고 있습니다.
앞으로 저는 문서 번역 자동화를 고도화해 글로벌 기술 문서를 더 빠르고 정확하게 번역하고 싶습니다. 다음에는 또 어떤 흥미로운 프로젝트로 여러분께 인사드릴지 저도 기대되네요. 😊
지금까지 ‘Teleport 공식 기술 문서 한글판 by 인포그랩’ 개발 후기였습니다. 읽어주셔서 감사합니다.
Teleport 도입과 사용 방법이 궁금하시면 지금 인포그랩에 문의하세요.