기술 문서 번역은 더 많은 사람들이 접근할 수 있도록 돕는 중요한 일이다. 해당 언어에 익숙하지 않은 사용자들이 새로운 기술을 배우고 적용할 수 있도록 많은 도움을 준다. 특히 오픈소스 프로젝트에 대해서는 기술 생태계를 확장하고, 더 많은 개발자들이 프로젝트에 기여할 수 있는 기회를 제공한다.

나는 현재 Vite의 한국어 문서 번역 프로젝트 메인테이너로 활동하고 있다. Vite는 매우 빠른 속도로 발전하는 차세대 프런트엔드 빌드 툴로, 매일 수많은 업데이트가 이루어진다. 이 글은 활발하게 개발되는 프로젝트에 대한 문서를 번역할 때 발생할 수 있는 문제와, 이를 해결하기 위해 개발한 Yuki-no라는 오픈소스를 소개하기 위해 작성했다.

번역 프로젝트는 여러 형태로 구성이 가능하다. Crowdin과 같은 상용 서비스를 이용하거나, VitePress나 Docusaurus와 같은 i18n을 지원하는 오픈소스 문서화 솔루션을 이용할 수 있다. 어떤 방법을 선택하든, 번역 작업은 원본 문서 변경에 대한 추적이 매우 중요하다. 그렇지 않으면 잘못된 부분을 번역하거나, 번역이 필요한 내용 중 일부를 빠트릴 수 있다.

Vite를 막 번역하기 시작했을 때 나는 이에 대한 중요성을 잘 알지 못했다. 원본 문서 특정 버전(커밋)을 목표로 번역을 진행했었는데, 절반 정도 진행하니 몇 문제들이 발목을 잡았다.

• 원본 문서와 차이점이 발생: 원본 문서는 계속 업데이트된다. 새로운 기능 설명이 추가되거나 API가 변경되면서 이미 번역한 내용이 종종 구버전이 되어버렸다.
• 필요하지 않은 부분을 번역: 최신 문서에서는 이미 삭제되었거나 변경되었는데, 이를 모르고 번역해버려 시간을 낭비했다.
• 번역 참여자들에게 설득이 어려움: "왜 이 버전에 대해 번역을 진행해야 하나요?"라는 질문에 적절한 답변을 제공하기 어려웠다. 어떻게 답변을 했지만, 스스로 납득되지 않았다.

모두 원본 문서와 동기화를 수행해주지 않아 발생한 문제다.

번역 프로젝트 작업 흐름

처음에는 수동으로 동기화 작업을 진행했는데, 상당히 비효율적이었다:

1. 시간 소모적인 확인 작업: 주기적으로 원본 저장소에 변경 사항이 있는지 수동으로 확인해야 했다.
2. 릴리스 상태 파악: 변경된 내용이 실제 릴리스된 기능인지, 아직 개발 중인 베타 기능인지 일일이 확인해줘야 했다.
3. 이슈 생성과 추적: 번역이 필요한 부분을 찾아 이슈로 생성하고, 해당 이슈를 추적하는 과정도 모두 수동으로 진행했다.

이러한 변경 사항을 확인하고 이슈로 만드는 작업이 단순해 보이지만 실제로는 상당히 귀찮고 시간을 소모하는 일이다. 실제로 번역 자체보다 프로세스 관리에 더 많은 시간을 쏟게 되어 원활한 진행을 어렵게 만드는 요소 중 하나였다. 게다가 수동 작업 중 실수로 변경 사항을 놓치는 경우도 종종 발생했는데, 이럴 때는 정말 지루하고 의욕이 떨어졌다.

이러한 문제들을 효율적으로 해결하기 위해서는 동기화 과정을 자동화할 필요가 있었다.

Ryu-Cho는 원본 저장소에 대한 새로운 변경 사항을 이슈로 만들어준다

한계를 느낀 나는 (그제서야)다른 번역 프로젝트를 둘러보았다. React 진영은 직접 스크립트를 작성해 중앙 집중식으로 관리하고 있었고, Vue 진영은 오픈소스를 이용해 각 번역 프로젝트에서 동기화를 수행하고 있었다. 최종적으로는 Vue 및 다른 Vite 번역 프로젝트에서 사용하는 Ryu-Cho라는 오픈소스를 도입했다. 제공하는 기본적인 기능은 다음과 같다:

• 원본 저장소 커밋 모니터링
• 새로운 커밋에 대한 GitHub 이슈 생성

간단하지만 꽤나 강력하고 쓸모가 있었다. Vue.js 및 한국어 외 다른 언어를 대상으로 하는 Vite 번역 프로젝트에서도 사용중이어서, 신뢰도도 낮지 않았다. 그렇게 Ryu-Cho를 2년 가까이 사용했고, 아쉬운 부분이 눈에 보였다.

다음과 같은 문제점을 느꼈다:

• 릴리스 상태 추적 자동화 불가능
  • 번역 전 릴리즈 여부를 확인해야 하는 번거로움이 그대로 남아있음
  • 릴리스되지 않은 기능의 문서를 번역하는 경우 발생
  • 이를 일일이 추적한다면 수동 관리와 큰 차이가 없음
• 이슈 관리의 한계
  • 이슈 라벨링 기능 부재로 번역 이슈와 일반 이슈가 섞임
  • 작업 상태 추적이 어려워짐
• 설정과 유지보수의 어려움
  • 문제 발생 시 디버깅을 위한 로그 부족
  • 설정 옵션의 유연성 부족

새로운 도구의 필요성을 느꼈다. 그렇게 Yuki-no를 개발했다.

Yuki-no 로고 / 소개 페이지 / GitHub

Ryu-Cho 한계를 극복하기 위해 개발된 Yuki-no는 현재 Vite 한국어 문서 번역 프로젝트, Vue 한국어 문서 번역 프로젝트, 그리고 Vite 번역 템플릿에서 실제로 사용중이다.

Yuki-no 동작 방식

1. 자동화된 변경 사항 추적

   Yuki-no로 생성된 Vite 한국어 번역 프로젝트 이슈 목록 중 일부

   • 원본 저장소 내 필요한 부분에 대한 변경 사항만을 모니터링
   • 번역이 필요한 부분을 GitHub 이슈로 생성 및 라벨링
   • 배치 처리를 통한 효율적인 GitHub API 사용

2. 릴리스 상태 기반 번역 관리

   Yuki-no로 관리되는 릴리스 코멘트 및 라벨

   • 정식 릴리스된 내용과 프리 릴리스 버전 구분
   • 릴리스 상태에 따른 라벨링
   • 불필요한 번역 작업 방지

3. 효율적인 작업 관리

   • 번역이 필요한 부분만 한눈에 파악 가능
   • GitHub 기반 이슈 관리 프로세스 그대로 사용 가능
   • 최적화된 GitHub API 사용으로 안정적인 운영

Yuki-no는 GitHub API를 효율적으로 사용하기 위해 다음과 같은 최적화를 적용했다:

GitHub Actions 런타임 로그

• 커밋을 5개씩 묶어서 배치 처리해 API 호출 최소화
• 배치 작업 간 3초 지연 시간을 적용해 짧은 시간에 API 호출이 몰리지 않도록 만듦
• API 요청 한도 초과 등 실패 상황 발생 시 다음 Action에서 자동으로 재시도하는 메커니즘 구현

덕분에 200개가 넘는 변경 사항에 대해 GitHub Issues를 생성하는 작업도 무리 없이 처리할 수 있었다. 또한 상세한 로그와 함께 실시간 진행률을 보여줘, 현재 어디까지 진행했는지 쉽게 확인할 수 있도록 구성했다.

아래 내용은 리드미에서도 확인할 수 있다. 만약 Ryu-Cho 또는 이와 유사한 방식으로 번역 프로세스가 구성되어 있다면 마이그레이션 문서를 참고하자.

먼저 저장소에 GitHub Actions 권한을 설정해야 한다. 이는 Actions에서 Issues 및 Issue Comments를 생성하기 위해 필요하다. 참고로 Ryu-Cho와 같은 GitHub Issues 기반 번역 프로세스를 구축하는 모든 Actions에서 이를 요구한다:

GitHub Actions 권한 설정을 해주지 않으면 에러가 발생한다

• 리포지토리 Settings 탭으로 이동 > Actions > General > Workflow permissions 항목
• "Read and write permissions" 선택
• 변경 사항 저장

다음으로 .github/workflows/yuki-no.yml 파일을 생성해야 한다. 자세한 내용은 Yuki-no 문서를 참고하자. 가령 Vite 번역 프로젝트를 시작한다고 했을 때, 아래와 같이 구성할 수 있다:

# .github/workflows/yuki-no.yml

name: yuki-no

on:
  schedule:
    - cron: '0 * * * *' # 매시간 실행
  workflow_dispatch: # 수동 실행 옵션

jobs:
  yuki-no:
    runs-on: ubuntu-latest
    steps:
      - uses: Gumball12/yuki-no@v1
        with:
          access-token: ${{ secrets.GITHUB_TOKEN }}
          head-repo: https://github.com/vitejs/vite.git
          track-from: abcd1234 # 추적을 시작할 커밋 해시
          include: |
            docs/**
          release-tracking: true

이제 번역 작업은 이렇게 진행하면 된다:

1. 자동 이슈 생성

   • track-from 커밋부터 시작해, 원본 문서가 업데이트되면 자동으로 이슈 생성
   • 릴리스 상태도 자동으로 추적
   • 커밋에 대한 정보 포함

2. 작업 현황 관리

   • 라벨로 작업 상태 관리 (예: 번역 이슈는 sync이 붙음)
   • 릴리스 추적 라벨로 우선순위 파악 (예: 정식 릴리스되지 않은 변경 사항에는 pending이 붙음)
   • 작업자 배정 및 진행 상황 추적

3. 번역 및 리뷰

   • PR 생성 및 리뷰 진행
   • 릴리스 상태에 따른 번역 및 배포 시점 조절

1. 파일 패턴 활용

   include: |
     docs/**/*.md        # 문서 파일만 추적
     .vitepress/config.ts # 설정 파일도 포함
   exclude: |
     docs/**/*.test.ts   # 테스트 파일 제외
     docs/internal/**    # 내부 문서 제외
   

   • include로 번역이 필요한 파일만 선택적으로 추적
   • exclude로 불필요한 파일 제외
   • Glob 패턴을 사용해 유연한 파일 선택 가능

2. 릴리스 추적 시스템 활용

   release-tracking: true
   release-tracking-labels: |
     pending
     pre-release
     released
   

   • release-tracking: 릴리스 상태 자동 추적 활성화
   • release-tracking-labels: 릴리스 상태별 라벨 지정
   • 라벨 및 이슈 코멘트를 통한 릴리스 상태 확인

   동작 방식:

   • 새 커밋이 감지되면 sync 라벨로 시작 (labels 옵션을 통해 지정, 기본값 sync)
   • 정식 릴리스 이전 변경 사항은 pending 라벨이 붙음 (release-tracking-labels 옵션을 통해 지정, 기본값 pending)
   • 릴리스 상태 변경 시 이슈에 코멘트 자동 추가
   • 정식 릴리스 시 pending 라벨 제거됨

Yuki-no를 도입한 후, Vite 한국어 문서 번역 프로젝트는 이런 개선을 이루었다:

• 불필요한 번역 작업을 피할 수 있게 됨
• 번역 작업 만족도 향상
• 번역 진행 방식 간결화 및 진입 장벽 낮춤

현재 Vite 한국어 문서 번역 프로젝트는 Yuki-no를 통해 안정적이고 효율적인 번역 프로세스를 운영하고 있으며, 이는 다른 번역 프로젝트에도 좋은 참고 사례가 될 수 있을 것이라 생각한다.

더 자세한 내용은 Yuki-no 문서를 참고하자. 질문이나 제안이 있다면 GitHub Issues에 남겨주기를 바란다.