Localizeflow를 만든 이유

기술 문서는 살아 있는 문서다

기술 문서는 제품과 함께 계속 변합니다. 기능이 추가되면 문서를 수정해야 하고, 그 변경은 모든 언어에도 즉시 반영되어야 합니다. 문장을 번역하는 것보다 번역본을 최신 상태로 유지하는 것이 훨씬 더 어렵습니다.

실제로 운영을 해보면 반복 작업이 계속 발생합니다. 어떤 페이지가 언제 바뀌었는지 추적해야 하고, 번역이 필요한 영역을 다시 찾아 반영해야 하고, code, HTML, frontmatter 같은 요소가 깨지지 않게 신경 쓰면서 결과물을 PR로 정리해 리뷰까지 받아야 합니다. 문서가 많고 폴더 구조가 복잡할수록 이 작업은 더 무거워집니다.

이 과정에서 가장 크게 느낀 점은 단순합니다. 문서는 번역보다 유지가 더 어렵다.

FastAPI 사례에서 확인한 문제의 보편성

FastAPI 팀은 2025년 커뮤니티 기반 번역 PR 운영을 중단하고 내부 자동화 파이프라인으로 전환한다고 발표했습니다.

이 문제는 특정 프로젝트의 문제가 아닙니다. 문서를 운영하는 대부분의 팀이 동일한 문제를 겪습니다. 대형 프로젝트는 자체 시스템을 만들 수 있지만, 초기 스타트업이나 작은 OSS 팀은 그렇지 못합니다.

Localizeflow는 바로 이 지점에서 시작되었습니다.

문서 운영 자체를 자동화하는 파이프라인이 필요했다

우리가 만들고 싶었던 것은 번역을 대신해주는 도구가 아니라 문서가 수정되었을 때 필요한 모든 작업이 GitHub 안에서 자연스럽게 이어지는 흐름 자체였습니다.

문서를 고치면 필요한 언어만 자동으로 다시 생성되고, Markdown 구조가 그대로 보존되며, code, HTML, frontmatter 같은 요소도 안전하게 유지되고, 이미지 텍스트가 번역되며, 최종적으로 깔끔한 PR로 정리되는 시스템.

GitHub App 하나로 이 모든 과정이 즉시 작동하는 시스템을 목표로 설계했습니다.

문장 번역이 아니라 ‘문서 구조 단위 재생성’을 선택한 이유

기존 번역 도구는 문장을 기준으로 판단합니다. 하지만 기술 문서는 텍스트보다 문서 전체의 구조와 문맥 일관성이 더 중요합니다.

Localizeflow는 문서의 변경 여부를 기준으로 전체를 재생성합니다. diff가 커질 수는 있지만, 용어·문맥·구조의 안정성 면에서 이 방식이 더 신뢰할 수 있음을 여러 프로젝트에서 반복적으로 확인해왔습니다.

Co-op Translator 엔진이 기반이 되다

Localizeflow는 Co-op Translator 엔진을 기반으로 합니다. 이 엔진은 단순히 번역 API를 감싼 도구가 아니라, 1년 넘게 실제 GitHub 문서를 번역·운영하며 기능을 확장해온 실전 엔진입니다.

현재는 Microsoft의 여러 오픈소스 문서 파이프라인에서도 사용되고 있습니다.

Markdown 파싱, 코드·HTML·frontmatter 보존, Mermaid 번역,
이미지 텍스트 처리, 용어 일관성 유지 같은 기능은
모두 “운영 과정에서 반드시 필요했던 기능”들입니다.

최근 Astro, Hugo, Docusaurus 같은 문서 엔진이 빠르게 확산되면서
문서의 규모는 점점 더 커지고, 글로벌 사용자 기반도 계속 늘어나고 있습니다.
문서를 최신 상태로 유지할 수 있는 능력 자체가 제품 경쟁력이 되는 시대입니다.

언어는 여전히 기술의 장벽이다

Co-op Translator를 운영하며 분명하게 느낀 점이 하나 있습니다.
여전히 너무 많은 개발자들이 언어 때문에 제대로 된 문서를 제때 읽지 못한다는 것입니다.

기술 문서는 제품의 핵심 구성 요소입니다.
문서를 제때 이해하지 못하면 학습 속도가 느려지고, 피드백 루프가 길어지고,
결국 제품의 성장 자체가 지연됩니다.

Localizeflow가 목표로 하는 바는 단순합니다.

“번역 시스템을 만드는 데 시간을 쓰지 않아도 되는 세상.”

DevRel 팀, 기술 문서 팀, SaaS 기업, OSS 메인테이너, 초기 스타트업까지
문서를 수정하면 모든 언어가 자동으로 갱신되고,
변경된 부분만 정확히 재생성돼 하나의 PR로 리뷰가 끝나는
GitHub-native 번역 파이프라인을 제공하는 것입니다.

Localizeflow는 그 미래를 만들기 위해 존재한다

여러 언어로 문서를 유지하는 일은 많은 팀이 결국 포기하는 지점입니다. 문서가 커지고 업데이트가 잦아지면 번역본은 금방 뒤처지기 시작합니다.

Localizeflow는 이 “포기하는 지점”을 없애기 위한 도구입니다. 번역을 쉽게 만드는 것이 아니라, 번역본을 지속적으로 최신 상태로 유지할 수 있게 만드는 시스템입니다.