오픈소스 프로젝트에 기여를 해보고 싶어서 제가 직접 사용하는 프로젝트부터 기여를 할 수 있는게 뭐가 있을지 생각해봤습니다. 그러다 한국어 문서에 기여를 해보면 어떨까? 라는 생각이 들었습니다.
그리고 제가 사용하는 OpenCode용 멀티 에이전트 플러그인 oh-my-opencode-slim의 한국어 README를 최신 영어 문서에 맞춰 정리하는 PR을 올렸습니다. 약 50분 만에 머지됐습니다. GitHub 스타 9,300개에 가까운 프로젝트입니다(작성 시점 기준).
처음에는 “영어 문서를 한국어로 다듬는 일”이라고 생각했습니다. 막상 시작해 보니 번역보다 콘텐츠 관리에 가까운 작업이었습니다. 원문이 바뀌면 번역문이 낡고, 용어는 제각각이 됩니다. 한국어 페이지와 영어 페이지를 함께 운영해 본 경험이 있다면 익숙한 문제들입니다.
이 글에서는 무엇이 문제였고, 어떻게 고쳤는지, 그리고 누구나 오픈소스에 기여할 수 있다는 것에 대해 적어 보겠습니다.
1. 문서는 “번역 실력”이 아니라 “관리”로 낡는다
이 프로젝트의 한국어 README는 이번이 처음 정리된 게 아니었습니다. 최초 번역(#502) 이후 수정(#727), 동기화(#935)가 있었고, 그 뒤에도 영어 원문은 계속 바뀌었지만 한국어 문서는 따라가지 못했습니다. 문서가 낡는 전형적인 패턴입니다. 만들 때는 최신이었지만, 유지되지 않으면서 조용히 틀리기 시작합니다.
가장 위험한 건 “실행하면 안 되는 안내”가 남아 있는 경우였습니다. 한국어 문서에는 번들 스킬을 강제로 교체하는 --skills=force 명령 사용법이 적혀 있었지만, 그사이 스킬 관리 방식 자체가 바뀌어 해당 명령은 더 이상 쓰이지 않았습니다. 문서를 믿고 따라 한 독자는 존재하지 않는 명령을 실행하게 됩니다.
작은 것도 있었습니다. 상단 릴리스 배너 이미지가 여전히 V2였고(영어 원문은 V3 베타), 설정 예시 JSON도 영어 원문과 다른 상태였습니다. 배너 한 장, 예시 한 블록도 콘텐츠입니다. 원문과 어긋나는 순간 독자를 잘못된 방향으로 인도합니다.
2. 번역투 걷어내기 = 용어와 톤의 표준화
번역이 어색해지는 건 실력 문제라기보다 기준 부재의 문제인 경우가 많습니다. 이번 작업에서는 세 가지 기준을 세웠습니다.
브랜드 표기와 용어를 통일했습니다 “Opencode 멀티 에이전트 스위트”처럼 브랜드 대소문자가 틀리고 어색한 외래어가 섞인 표현은 “OpenCode 멀티 에이전트 도구 모음”으로 바꿨습니다. “인스톨러”는 “설치 프로그램”으로 정리했습니다.
남아 있던 영어를 한국어로 옮겼습니다. 에이전트 역할 설명에 `Codebase reconnaissance`, `Multi-LLM consensus and synthesis` 같은 영어 문자열이 그대로 남아 있었습니다. 각각 “코드베이스 탐색”, “여러 언어 모델의 합의 도출 및 의견 종합”으로 옮겼습니다. 반대로 명령, 설정 키, 모델 ID, 에이전트 이름은 번역하지 않았습니다. 실행되는 것과 설명되는 것을 구분하는 규칙입니다.
약어는 처음 나올 때 풀어 썼습니다. “LSP 도구”는 “언어 서버 프로토콜(LSP) 도구”로, “AST 인식 검색”은 “추상 구문 트리(AST) 기반 검색”으로. 한국어 독자에게 낯선 약어를 그대로 두면 문서가 아니라 암호가 됩니다.
톤도 기준이었습니다. 이 프로젝트의 README는 “코드의 여명에서 일곱 신성한 존재가 나타났습니다” 같은 신화적 문체를 씁니다. 번역하면서 이 목소리를 평범하게 눌러 버리면 개성이 사라지므로, 문장은 다듬되 톤은 유지했습니다. 가령 직역투인 “백만 개의 코드베이스 복도를 누빈”은 “백만 개의 코드베이스를 누빈”으로 고쳤습니다.
용어집과 스타일 가이드를 만들고, 그 기준을 수십 개 문자열에 일관되게 적용하는 일. 콘텐츠 팀의 일상과 정확히 같은 작업입니다.
3. 체크리스트로 검수하고, 못 한 것은 못 했다고 적기
콘텐츠 작업은 “고쳤다”가 아니라 “확인했다”로 끝나야 합니다. PR에는 다음을 검증했다고 적었습니다.
- 문서 안의 링크와 이미지 경로가 실제로 존재하는지
- 앵커와 코드 블록이 깨지지 않았는지
- 설정 예시가 영어 원문과 일치하는지
- 기여자가 작성한 섹션은 건드리지 않았는지
git diff --check로 공백 오류가 없는지
한 가지 원칙을 더 지켰습니다. 영어 원문이 모호한 부분은 임의로 해석하지 않고 PR 설명에 따로 남겼습니다. 원문 자체에 Companion 표 설명의 불일치나 Orchestrator의 `high`/`medium` 표기 문제가 있었는데, 번역자가 추측으로 메우면 나중에 원문이 수정될 때 번역만 틀린 상태가 됩니다. 원문이 의심스러우면 고치는 게 아니라 질문하는 편이 맞습니다.
로컬 환경에 개발 의존성이 없어서 포맷터·타입 검사·테스트는 돌리지 못했습니다. 이 사실도 PR 본문에 그대로 적었습니다. 못 한 검사를 한 것처럼 보이게 하지 않는 것도 검수의 일부입니다.
4. 리뷰 봇과 메인테이너, 그리고 머지
PR을 올리자 몇 분 만에 자동 리뷰 봇(Greptile)이 요약 리뷰를 남겼습니다. 그중 하나는 실제 개선점이었습니다. “Council 키워드를 쓰려면 구성원 설정이 먼저 필요하다”는 전제가 안내에 빠져 있다는 지적이었습니다. 이 지적은 머지 시점에 반영되지 않았고 아직 열린 스레드로 남아 있습니다. 다음 기여에서 이어서 처리할 항목으로 적어 두었습니다.
약 50분 뒤 메인테이너가 PR을 머지했습니다. 범위를 좁게 잡은 것이 도움이 됐습니다. “문서만 변경, 런타임 코드 변경 없음”, “명령·설정 키·모델 ID·에이전트 이름은 그대로”. 리뷰어가 확인할 표면이 작을수록 콘텐츠 PR은 빨리 받아들여집니다.
5. 웹 콘텐츠 관리와의 연관성
제가 한 일을 나열하면 이렇습니다.
- 원문과 번역문의 동기화
- 용어집·스타일 가이드에 따른 표기 통일
- 링크·이미지·예시·구조를 확인하는 QA 체크리스트 운영
- 범위를 명시하고, 모호한 원문은 임의 해석 대신 질문으로 남기기
- 리뷰 피드백을 확인하고 후속 항목 관리
문서 사이트에서 하든 회사 홈페이지에서 하든 과정은 같습니다. 제 블로그도 워드프레스와 Polylang으로 한국어(기본)와 영어(/en/)를 함께 운영합니다. 언어가 두 개가 되는 순간부터 같은 문제가 시작됩니다. 이번 PR은 그 문제를 작은 규모로 연습한 셈입니다.
결과
부트캠프에서 깃허브로 프로젝트를 하면서 코드도 작성하고 풀 리퀘스트도 올리고 했지만 실제로 사용자가 있는 프로젝트에 기여를 했다는게 신기하네요. 한국 사용자들이 oh-my-opencode-slim을 사용할 때 도움이 될 수 있길 바랍니다.
마치며
코드가 아니어도 오픈소스에 기여할 수 있습니다. README에서 낡은 안내 하나를 찾아 문제를 정리하고, 범위를 적어 PR로 올리면 됩니다. 이번에도 이슈로 문제를 먼저 정리하고(#1422) PR을 올렸습니다(#1423). 그 순서 덕분에 “무엇을, 왜 바꾸는지”를 리뷰어에게 설명하기 쉬웠습니다.
10월은 Hacktoberfest의 달이기도 한데 이 글을 읽는 분들도 오픈소스 프로젝트에 한번 기여를 해보시는것도 좋을 것 같습니다.
작업 기록도 남겨 둡니다.