• .

• 나는 Vite에 한국어 문서 번역 프로젝트 메인테이너로 기여하고 있다
  • 이를 진행하며 다양한 상황을 맞닥뜨렸고, 하나씩 해결해 갔었다
  • 여기서는 기존 번역 방식에 대한 한계 및 해결에 대해 다뤄본다
• 앞서 Cursor 이용한 번역 경험이나 Yuki-no 개발기에서도 언급했듯
  • 빠르게 변화하는 오픈소스 문서를 번역한다는 것은 전문가가 아닌 이상 적지 않은 리소스를 꾸준하게 투자하는 건 쉽지 않은 일이다

S:

• 나는 Vite에 한국어 문서 번역 메인테이너로 기여중
• Cursor로 Vite 한국어 문서 번역 진행한 경험이나 GitHub으로 기술 문서 번역 프로젝트 시작하기에서도 언급했지만
  • 번역은 지속적으로 리소스 부어야 하고
  • 상대적으로 은근히 꾸준하게 리소스가 들어가는 작업
  • 왜? Vite는 많이 바뀌는데 이걸 처리하는 인원은 상대적으로 많지는 않으니
• 저 이후 번역할 때 AI를 많이 사용하는데 그래도 뭔가 비효율적이더라
• 프로세스를 설명하자면 이런데
  • 이슈에서 번역 관련 변경사항 확인
  • 번역 리포지토리에 해당 내용 번역해 집어넣음
  • 커밋 & push
  • 좀 별로임 이거…

T:

• 이게 문제점이 있음
  • 순차적으로 해야하는데, 이러다보니 이후 변경사항에서 삭제되거나 내용이 바뀌는 경우가 있음
    • 근데 왜 순차적이냐, 히스토리를 따라가야 변경사항 제대로 반영되기에
    • 그래서 무의미한 리소스 소모가 많았음
  • 그렇다고 한번에 모두 반영하고 번역돌리자니 귀찮았음
    • 양이 적은것도 아니고 얼마나 걸릴지 모르는데 로컬에서 작업하고 있다가 외부에서 기여가 들어오면?
    • assign 해두면 되긴 하지만 이런 과정들이 번거롭고 귀찮았음
  • 일부만 하면 된다, 한번에 날 잡고 하면 되지 않냐 다양한 방법이 떠오를 수 있겠지만
    • 그냥 그런 과정 모두가 귀찮았음 무의미한 리소스 쏟는 느낌이었고
• 그렇게 번역하다 어느순간 여기서 벗어나야겠다는 생각이 듦
  • 그렇게 Yuki-no 다음 버전을 만들어야겠다 생각함
  • 6월 25일부터 작업 진행했고, 8월 7일 어제 작업이 어느정도 완료되어서
  • 이를 이용해 약 2800 라인 Diff를 번역 관련 번경 사항을 하루만에 작업 완료했음
• 여기서는 내가 뭘 만들었고 어떻게 번역 작업했는지 소개하고자 함
  • 이걸 바탕으로 다른 번역 리포지토리에도 소개할건데 바로 In Action 하고자 한다면 이 섹션으로 이동하길 바람

A(yuki-no):

• 먼저 Yuki-no 자동화임
  • 자동화는 이전부터 생각해왔었음
  • 다만 어떻게 접근하면 좋을지 고민하다 이전에 개발한 Yuki-no를 확장해보면 어떨까 하는 생각이 듦
• 이를 위해 먼저 확장성을 다시 생각해보자 생각했음
  • 어차피 취미로 하는 프로젝트고 이전부터 생각했던 GitHub Actions에서 플러그인 시스템을 도입해보고자 생각도 했어서
  • 앞으로도 새로운 기능 도입될텐데 플러그인으로 서로 독립적으로 구성할 수 있으면 좋겠다 생각햇음
  • 또 GitHub Actions에서 플러그인 시스템을 구축한 사례를 못봐서
    • 왜 없었을까?
• 깊이 다루지는 않겠지만 간단히 다음과 같은 시스템으로 구성함
  • (그림)
  • Yuki-no 라이프사이클을 만들고 각 지점마다 호출되는 훅에 대한 인터페이스 정의
  • 그리고 플러그인 목록을 action으로 전달받아 이를 Yuki-no 시작 전 npm 레지스트리에서 설치해 사용
• 덕분에 핵심 로직만 core로 남길 수 있었고
  • 릴리스 추적이나 이번에 개발한 배치 PR 기능을 플러그인으로 성공적으로 분리할 수 있게 됨
  • 이후 AI 번역도 추가할 계획이라 플러그인 분리가 적절했다고 생각되었음
  • 이를 쉽게 배포하기 위해 cd 파이프라인도 조금 손봤고
• 릴리스 추적은 GitHub으로 기술 문서 번역 프로젝트 시작하기 블로그 글에서 설명하고 있음
  • 이건 @yuki-no/plugin-release-tracking 이라는 이름으로 npm 배포했고
  • 하위호환성 지키는 로직도 구성함
• 그럼 배치 PR은 뭐냐
  • 앞서 번역 프로세스에서도 언급했는데
    • 번역 관련 변경 사항을 번역 리포지토리에 모두 적용시키는 기능만을 담당하는 플러그인임
    • 리포지토리 A에 존재하는 커밋 중 일부(번역 관련)만 취해서 이를 리포지토리 B에 적용시키는 것
  • 단순히 변경사항을 이동시키는건 아니고 몇 가지 고려사항이 있음
    • 루트 디렉터리가 다를 수 있음
      • 실제로 vite 한국어 문서가 그랬는데
      • 원본 리포지토리에서는 문서 관련 내용이 docs 디렉터리 아래에 있었는데(vite/docs/)
      • 번역 리포지토리에서는 루트에 문서 관련 내용이 있었음(docs-ko/)
      • 그래서 이를 지정할 수 있도록 해야 함
    • 또한 수동으로 적용해야 하는 변경 사항이 있을 수 있음
      • package.json이나 관련 설정이나 의도적으로 수동으로 관리하는 문서 등
    • 마지막으로 "실제로 무엇이 변경되었는지" diff를 확인해서 이동시켜야 함
      • 단순히 파일 단위로 이동시키면 기존 번역 내용이 모두 날아가기 때문
  • 이것도 간단하게 설명하자면
    • 수동으로 적용해야 하는 변경 사항은 기존 picomatch 기반 작성한 함수 있어서 이를 그대로 이용
    • 변경사항 적용은 로직을 구현해야 했는데 크게 2가지로 분리해서 진행함
      • (생각해보니 이것도 npm 라이브러리로 만들어도 좋을듯, 아니면 이미 있으려나?)
      • git diff에서 변경사항을 추출해 FileChange라는 데이터 구조로 만드는 extractFileChanges
      • FileChange 배열을 전달받아 이를 통해 실제 파일을 수정하는 applyFileChanges
  • 아무튼 이렇게 구현했고 @yuki-no/plugin-batch-pr 이라는 플러그인으로 만들어 npm 배포 완료

R(yuki-no):

• 그렇게 지금 vite 한국어 번역 문서 프로젝트를 alpha test 필드로 삼아 해봤는데 잘 굴러가고 있는 것 같다
  • 몇 가지 개선사항이 있긴 하지만
    • 수동으로 관리하고자 하는 목록을 pr body에 보여준다던가
    • pr 안만들어도 되는 상황에서는 만들지 않는다던가 등
  • 그건 차차 추가하기로 하고, 가장 핵심 기능인 변경사항 모두 취합해 PR 하나로 만들어주기 기능은 잘 동작하는 것으로 보임
• vsc + cline ext + claude code
  • claude max 플랜 구독해 claude code 바탕으로 sonnet-4와 opus-4 번갈아 사용
    • cursor 쓰다가 너무 사용량이 부족해 claude max 플랜에 vsc에 cline 이라는 오픈소스 익스텐션 붙여서 사용중
      • 여기에 sequential thinking, tavily, file system, context7 정도만 mcp 붙이고
      • 커뮤니티와 ai 도움받아 작성한 cline rules 바탕으로 사용중
    • 물론 cursor가 20 플랜이긴 해도 좀 많이 심각하게 부족했음
      • 한동안은 이 형태로 가지 않을까
  • conductor도 써봤는데 토큰과 cost를 너무 많이 소모해서 별로
    • 동일한 mcp 붙여서 사용했는데 내부 프롬프트가 좀 다른듯
• 근데 sonnet-4 위주로 사용하긴 했지만 완벽하진 않더라
  • 특히 코드베이스를 결국 이해해야 한다는 건 마찬가지였음
  • 케이스 찾아보기 어려운 특정 버그는 거의 도움을 받기 어렵더라
  • 대신 코딩&디버깅 시간보다 리뷰 시간이 이전에는 9:1이었다면 지금은 2.5:7.5정도가 된 느낌
• claude code pr review
  • cc에서 first-party로 제공하는 기능인데 꽤 좋았음
  • 로컬에서 사용중인 cline rules 바탕으로 pr review rule 만들고
    • github action 이용해 pr review 하도록 파이프라인 구성해서 가능한데
    • 나는 추가로 @claude <prompt> 라는 코멘트 붙었을 때만 pr review 하도록 구성함
  • 아무튼 상당히 구체적이고 다각적으로 코드 분석해줘서
    • 실제로 구현한 코드에서 놓쳤던 부분(로컬에서 한번 cc로 검증 거쳤음에도 있었다)도
    • 얘가 잡아주기도 했음

A(translation):

• 그래서 이렇게 개발한 batch-pr 플러그인으로 번역 필요한 모든 변경사항을 하나의 PR로 자동으로 모을 수 있게 되었음
  • 아직 정식 배포는 아니고 wip 버전으로 지금 vite 한국어 번역 프로젝트에서 사용중이지만
  • 한 달 정도 보고 정식 배포 진행할 예정
• 이렇게 만든 pr은 https://github.com/vitejs/docs-ko/pull/1268 에서 확인할 수 있음
  • batch-pr 결과: https://github.com/vitejs/docs-ko/compare/a34c8d7bd4beb9e68d3b3349ffed94c96b2b11c1..68afebcd27172dd65b557069a3d6e3b26f166889
  • missing contents: https://github.com/vitejs/docs-ko/pull/1268/commits/cc017a35ce02306622336182a5f2231dcc2a98d9
    • 지금은 해결된 버그로 인해 누락된 .vitepress 디렉터리 아래 변경사항과
    • 의도적으로 포함시키지 않도록 설정한 파일을 반영
• 이는 git history에 존재하고, 이 diff를 바탕으로 cc로 1차 번역 해달라고 했음
  • https://github.com/vitejs/docs-ko/pull/1268/commits/6dee54f88f17fc86a7317c3fe5f748225e10ef1a
  • 당연히 이게 완벽하진 않아서 내가 리뷰 한번 거치긴 했다만
  • 룰을 좀 더 상세하게 정해서 번역하도록 하면 리뷰를 조금 덜 수 있을 것 같음
    • (프롬프트 파일)
    • 이를 위한 ai 에이전트나 특정 툴에서 독립적인 룰 파일도 만들었다
    • 이걸 참고해서 번역하라 할건데 잘 동작하는지는 지켜볼 예정
• 이후 리뷰 내용을 바탕으로 AI & 수동으로 수정했고
  • 엄청 많지는 않아서(작은 범위 단위 53개 정도), 5시간정도 소모해 번역 모두 완료했다
  • 대부분 번역이 잘 되어서 그냥 원문과 함께 한번 읽어보고 이상하게 다가오는 부분만 교정해줌
• 총 5~6시간 정도 걸려서 엄청 많은 변경사항(81개, 2800라인/68파일 Diff)에 대한 번역 완료했다
  • 결과물도 꽤 만족스러웠음

R(translation):

• 처음보다 조금 길어지기는 했지만 프로토타입 버전은 잘 만들어졌다 생각함
  • 기존 리소스를 많이 차지하는 부분을 자동화한 부분이 상당히 컸음
  • 원래 방식대로 진행했다면 1주일 조금 더 걸리지 않았을까
  • 하는것도 재미없었을거고 스트레스만 되었을거고
• 이후 1차 초벌 번역 플러그인도 만들 예정이다
  • 이것도 자동화 가능해보임
  • 다만 먼저 홍보부터 하고… (ai 번역 플러그인 넣는다 해도 ai 구독 필요한데, 이건 일단 구현없이도 로컬이지만 가능해서)
• 최종적으로는 내가 리뷰만 하고 리뷰 바탕으로 AI가 추가 수정하거나 내가 직접 수동으로 수정해서
  • 리소스를 최소화할 예정
  • 이로 인해 외부 기여는 많이 줄어들지 않을까 (리소스 필요한 부분이 많이 덜어졌으니)
• 또한 더 나아가 비슷하게 번역 프로젝트 관리하는 데 힘 부치는 사람들 위해서 이거 도입을 도와주고 싶다
  • 분명 나처럼 매너리즘 빠졌거나 힘들텐데 도움이 될 수 있으면 좋겠다
  • 도울 수 있는게 있을지 모르니 필요하면 언제든 편하게 연락주라

R(conclusion):

• 그 외로 개발에 cc를 많이 사용했다
  • (사진)
  • 큰 의미는 없지만 claude $100 max 사용중인데 만약 api로 같은 작업 했다면 약 $1000 이상 사용했을거라고 찍힌다
  • 상당히 도움이 되었고
• 그리고 몇 주 전에 cc subagents 나왔다고 하던데 cc pr review 비슷한건가?
  • 사용 예시를 보았지만 크게 다가오지는 않고 완전 100% vive 코딩을 하는건 아니어서(결국 리뷰해야하는) conductor와 함께 사용 안하는 툴이 되긴 했지만
  • 이렇게 빨리 ai 툴 나오고 그런거 보면 사용 예시 보면서 무엇을 할 수 있는지 간단하게라도 계속 보는게 중요한 듯
• 퇴사 후 8개월, 이제 모아둔 돈도 슬슬 떨어지고 어쨌든 수입이 필요한 상황임
  • 아마 회사를 들어가게 될 것 같은데, 백수생활 청산하면 이런 경험을 바탕으로 생산성 많이 끌어올려보고싶다