Localizeflow로 내 다국어 문서를 자동화한 방법

문제점: 번역은 어렵지 않았다. 동기화가 문제였다.

지난 세 달 동안, 저는 문서와 블로그 콘텐츠를 한국어와 영어로 동시에 운영해 왔습니다.

제 워크플로우는 간단했습니다:

한국어로 초안 작성.
영어 버전 생성.
두 언어 모두 시간 경과에 따라 유지.

처음에는 관리가 가능해 보였습니다.
많은 경우, AI에게 다른 언어를 업데이트해 달라고 요청할 수 있었고, 의외로 잘 작동했습니다.

한동안은 효율적이라고 느꼈습니다.

하지만 문서가 점점 더 빨리 발전하기 시작하자 — 새로운 기능, 업데이트된 스크린샷, API 변경 — 문제가 조용히 발생하기 시작했습니다.

영어 버전을 업데이트할 때마다:

한국어도 업데이트가 필요하다는 걸 기억해야 했고,
변경 사항을 수작업으로 찾아내야 했으며,
놓친 부분이 없는지 다시 확인해야 했습니다.

처음에는 두 버전을 꽉 맞추어 동기화했습니다.

그러나 어느 순간 불편한 사실을 깨달았습니다:

영어 문서를 즉시 업데이트하면서…
“나중에 한국어 업데이트하겠다”고 자꾸 말하고 있었습니다.

그 ‘나중’은 거의 오지 않았습니다.

번역 자체가 어려운 부분은 아니었습니다.

두 언어를 동기화하는 것이 어려웠습니다.

그리고 창업자로서 저의 집중은 오래된 문장을 언어별로 쫓아다니는 것이 되어서는 안 되었습니다.

어느 순간 다소 아이러니한 사실을 인지했습니다:

저는 현지화 자동화 제품을 만들면서
제 다국어 문서를 수동으로 관리하고 있었습니다.

그건 말이 안 됐습니다.

그래서 저는 Localizeflow 자체 문서와 블로그에서 Localizeflow를 직접 도입하기로 결정했습니다.

결정: 자동화하거나 언어를 포기하거나

현실적인 선택지는 두 가지뿐이었습니다:

한국어 유지 중단
혹은 워크플로우 자동화

언어를 포기하는 건 옳지 않았습니다.
하지만 수동으로 계속하는 것도 비효율적으로 느껴졌습니다.

다국어 문서가 꾸준한 관리와 주의력을 필요로 한다면,
빠르게 변화하는 스타트업에서는 유지되기 어렵습니다.

그래서 언어를 없애는 대신에
마찰을 제거하기로 했습니다.

저는 문서 저장소에 Localizeflow를 설치했습니다.

YAML도 없고,
추가 설정도 없고,
그냥 GitHub 앱 설치만 했습니다.

그게 전부였습니다.

새 대시보드도 원하지 않았고,
새 번역 포털도 원하지 않았습니다.

기존의 GitHub 워크플로우가 그대로 유지되길 원했습니다.

그리고 실제로 그랬습니다.

정확한 통합 플로우가 궁금하다면, 설정 가이드를 확인하세요:
https://docs.localizeflow.com/

조금 더 자세히 들어가기 전에, 스택에 대해 짧게 말씀드리겠습니다.
저희는 정적 사이트 생성기로 Astro를 사용합니다.
Astro는 다른 일부 문서 프레임워크처럼 강력한 다국어 지원을 기본으로 제공하지 않습니다.

이건 의도된 선택입니다.

Localizeflow가 더 덜 “도와주는” 환경에서 잘 작동하는지 먼저 테스트하고 싶었습니다.
Astro에서 잘 작동한다면, Hugo, Docusaurus 또는 Mintlify와 같이 더 강력한 i18n 기본 기능이 있는 곳에서도 더욱 원활할 것입니다.

이제 실제로 무엇이 바뀌었는지 말씀드리겠습니다.

실제 설정 모습

가입 과정에서 GitHub 앱을 설치한 후, “Connect repositories” 버튼을 클릭하여 문서 저장소를 연결했습니다.

연결이 완료되면 저장소를 클릭하여 온보딩 플로우로 들어갑니다.

긴 설정 과정 대신, 세 가지 선택사항만 있었습니다:

언어
출력 구조
용어집 규칙

전체 과정은 몇 분밖에 걸리지 않았습니다.

특별히 놀라웠던 점은 속도뿐 아니라
인프라스트럭처를 수정할 필요가 없다는 점이었습니다.

CI 스크립트를 추가하지도 않았고,
폴더 구조도 바꾸지 않았습니다.

기존 저장소가 어떻게 작동하는지만 확인했을 뿐입니다.

이건 중요했습니다.

왜냐하면 제 경험상 “자동화” 도구들은 보통 시스템 변경을 요구하기 때문입니다.

하지만 이 도구는 그렇지 않았습니다.

1. 대상 언어 선택하기

첫 번째 결정은 대상 언어를 선택하는 것이었습니다.

각 언어는 별도의 번역 Pull Request 스트림이 됩니다.
이런 설계 덕분에 변화가 눈에 잘 띄고 숨겨지지 않습니다.

GitHub 워크플로우에 자연스럽게 맞아떨어집니다.

2. 번역 파일 위치 정의하기

출력 경로는 저장소 분석 기능을 사용했습니다.

저장소를 스캔해 소스 및 대상 경로를 제안해주었습니다.

제안을 검토하고 확인했습니다.

계속 진행하기 전에, 번역이 생성된 후 폴더 구조가 어떻게 보일지 미리 확인했습니다.

이 미리보기는 중요했습니다.

아직 아무 것도 변경하지 않은 상태에서
번역 파일이 정확히 어디에 위치할지 보여주었습니다.

폴더 매핑에 대해 수작업으로 고민할 필요가 없었습니다.

단지 시스템이 기존 구조에서 추론한 내용을 검증하면 되었습니다.

3. 용어집 규칙 설정

설정을 마치기 전에 간단한 용어집을 추가했습니다.

예를 들어:

Localizeflow
GitHub App
Co-op Translator

이러한 용어는 번역 과정에서 변경되지 않습니다.

나중에 반복되는 PR 수정 작업을 줄일 수 있습니다.

총 설정 소요 시간

5분 미만이었습니다.

더 중요한 건:

CI 재구성 없음.
새 파이프라인 없음.
폴더 이동 없음.

설정을 새 시스템 도입처럼 느끼지 않고,
기존 시스템 내에서 기능을 활성화시킨 느낌이었습니다.

이제 영어를 편집하면 어떻게 되는가

실제로 바뀐 점은 다음과 같습니다.

이전에는:

영어 문서 편집
한국어 문서 수동으로 열기
변경 부분 탐색
업데이트
둘 다 커밋

이제는:

영어 Markdown 파일을 업데이트
Localizeflow가 해시 비교로 내용 변경 감지
자동으로 번역 Pull Request 생성
검토 후 머지

그게 다입니다.

더 이상 “번역 작업”을 하지 않습니다.
PR을 검토할 뿐입니다.

이 정신적인 차이가 큽니다.

설정 후에는 Localizeflow 대시보드를 적극적으로 확인하지 않습니다.

작업 진행 상황은 Pull Request에 구조화된 상태 업데이트로 직접 게시됩니다.

PR을 열면 즉시 볼 수 있습니다:

현재 진행 상황
완료된 언어
남은 작업
실패 여부

이것은 독립된 번역 도구보다 CI 상태처럼 행동합니다.

이 설계 덕분에 GitHub에 자연스럽게 녹아 듭니다.

실제로 개선된 점

1. 한 언어로 생각한다

이제는 영어 소스만 수정합니다.

더 이상 묻지 않습니다:
“한국어도 업데이트했나?”

인지 부하가 사라졌습니다.

2. 변경 사항이 쌓이지 않는다

예전에는 작은 업데이트도 양쪽 언어 모두 바꾸는 게 귀찮아서 미뤘습니다.

이제는 작은 문서 수정도 가볍게 처리할 수 있습니다.

그 결과 문서 품질이 간접적으로 개선됩니다.

3. 제 워크플로우 안에 머문다

모든 작업이 Pull Request를 통해 이루어집니다.

별도의 대시보드도 없고,
검토 후 머지하는 것뿐입니다.

4. 업데이트 시간이 몇 분으로 줄었다

예전에는 문서를 조금만 바꿔도 두 파일을 수정해야 했습니다.

이제는 지원 언어 수에 관계없이 한 페이지를 업데이트하는 데 걸리는 시간이 같습니다.

새 언어를 추가하는 한계 비용은 사실상 0입니다.

아직 개선이 필요한 점

Localizeflow를 직접 써보면서 몇 가지 한계도 발견했습니다:

Astro를 사용할 때, 번역이 생성된 후에 특정 URL을 수동으로 조정해서 현지화된 라우트를 제대로 참조하게 해야 했습니다. 이 문제는 더 강력한 내장 i18n 라우팅을 제공하는 정적 사이트 생성기에서는 달라질 수 있습니다.
헤더에 간단한 언어 전환기를 구현해, 현지화된 페이지 간 탐색을 쉽게 만들었습니다.

이런 작은 수작업 단계가 있어도, 전체 유지보수 노력은 크게 줄었습니다.

진짜 결과

이전에는:

두 언어를 유지하는 것이 부담처럼 느껴졌습니다.

지금은:

복수 언어 유지가 지속 가능하게 느껴집니다.

이 변화가 전략적 균형을 바꿉니다.

현지화가 고통스럽지 않을 때,
글로벌 도달은 부담이 아니라 기본이 됩니다.

마지막 생각

이건 제품이 잘 작동함을 증명하는 게 아니었습니다.

창업자의 실제 부담 속에서 워크플로우가 효과적임을 증명하는 것이었습니다.

기능을 만들고, 사용자와 소통하며, 운영을 처리할 때 —
문서는 가장 먼저 뒷전으로 밀립니다.

만약 다국어 문서가 철저한 관리가 필요하다면,
존속하기 어렵습니다.

PR 검토만으로 가능하다면,
존속할 수 있습니다.

Localizeflow를 직접 써보면서 한 가지가 분명해졌습니다:

번역은 쉽다.
진짜 문제는 동기화다.

그리고 동기화는 자동화할 수 있습니다.

대상 독자

이 워크플로우는 다음과 같은 분께 적합할 수 있습니다:

다국어 README를 관리하는 분
빠르게 움직이는 OSS 프로젝트를 운영하는 분
MDX가 많은 문서를 관리하는 분
예제, 스크린샷, API 참조를 자주 업데이트하는 분
소스 변경 후 번역 업데이트를 잊는 경향이 있는 분

문서 다국어 관리가 느릴 때만 가능하게 느껴진다면,
프로젝트 속도가 빨라질 때 살아남기 어렵습니다.

자동화가 책임을 없애는 게 아닙니다.
마찰을 제거하는 것입니다.

그리고 빠르게 움직이는 환경에서,
마찰 제거가 일관성을 가능케 합니다.

다국어 문서를 관리하시고, 이 방법이 저장소 내에서 어떻게 보일지 궁금하다면,
라이브 예시를 안내해 드릴 수 있어 기쁩니다.