Papermark가 Lingo.dev로 문서 로컬라이제이션을 자동화한 방법

Papermark는 오픈 소스 문서 공유 플랫폼입니다. 팀이 문서 로컬라이제이션을 결정했을 때, 대부분의 개발자 도구 팀이 마주하는 문제에 부딪혔습니다. Next.js 애플리케이션에서 i18n을 제대로 작동시키는 일이 번역 자체보다 더 어려웠던 겁니다.

세팅의 문제#

"시중에 나와 있는 자동화 패키지와 직접 만든 도구는 다 써봤어요,"라고 Papermark의 창립자 Iuliia Shnai는 회상합니다. "가장 큰 고충은 번역 단계조차 아니었어요. 저희 앱 구조에서 i18n이 제대로 작동하게 만드는 일이었죠."

익숙한 패턴입니다. 대부분의 로컬라이제이션 도구는 i18n 인프라가 이미 갖춰져 있다고 가정합니다. 번역은 해주지만, 설정이나 파일 구조, MDX 파싱, 프레임워크마다 다른 예외 케이스까지는 다루지 않습니다. 소규모 팀이 운영하는 오픈 소스 프로젝트에서 로컬라이제이션 세팅에 엔지니어링 시간을 쓰는 건 곧 제품 개발 비용으로 이어집니다.

여기에 MDX 파일, 즉 React 컴포넌트가 포함된 Markdown 기반 문서가 더해지면 복잡도는 한층 높아집니다. 일반적인 i18n 도구는 JSON 로캘 파일과 단순 문자열을 처리합니다. 하지만 컴포넌트 보간, 프런트매터, 커스텀 태그가 들어간 MDX 콘텐츠는 완전히 다른 접근이 필요합니다.

무엇이 달라졌나#

Lingo.dev의 창립자 Max가 직접 연락해 Papermark의 Next.js 프로젝트 구성을 도왔습니다. 그 구현은 팀이 막혀 있던 예외 케이스를 해결했습니다. MDX 파일 처리, next-intl과 앱 파일 구조의 상호작용, 그리고 컴포넌트 비중이 높은 문서에서 번역 가능한 문자열을 추출하는 작업까지 모두 포함됐습니다.

"이 구현은 우리가 미처 고려하지 못했던 수많은 예외 케이스를 처리해줬어요,"라고 Shnai는 말합니다. "특히 저희에게 큰 골칫거리였던 MDX 파일을 포함해, 로컬라이제이션의 복잡성을 정말 깊이 이해하고 있다는 게 분명했죠."

도입 첫날, 문서 80페이지가 번역됐습니다. Papermark의 제품 용어에 맞춰 구성하고 저장소와 연결한 로컬라이제이션 엔진이 전체 문서 세트를 자동으로 처리했습니다.

지금은 이렇게 작동합니다#

Papermark의 로컬라이제이션 엔진은 코드가 push될 때마다 실행됩니다. 새 문서가 추가되거나 기존 콘텐츠가 업데이트되면, 엔진이 변경된 내용을 자동으로 번역합니다. 엔지니어는 영어로 문서를 작성하고, 로컬라이즈된 버전은 별도 단계 없이 생성됩니다.

여기서 중요한 건 상태를 유지한다는 점입니다. 로컬라이제이션 엔진이 모든 요청에 걸쳐 Papermark의 제품 용어를 지속적으로 유지하기 때문에 "Data Room", "Link tracking", "NDA flow" 같은 제품 고유 용어도 모든 언어에서 일관되게 번역됩니다. 엔진을 거치는 첫 번째 문서 페이지든 백 번째 페이지든 동일한 제품 어휘가 적용됩니다.

"번역에 드는 지속적인 엔지니어링 노력 0"은 눈에 보이는 성과입니다. 하지만 그 밑바탕에는 로컬라이제이션이 반복 업무가 아니라 인프라가 되었다는 변화가 있습니다.