mdn 번역으로 오픈소스 기여하기

231211

들어가는 글

웹 프론트엔드 개발자로 일하며 가장 많이 본 사이트는 stackoverflow도 GitHub도 아닌 mdn이었다. mdn은 오픈소스로서 HTML, CSS, JavaScript, Web API 등의 다양한 정보를 제공하고, 처음 개발에 입문하는 사람들을 위해 가이드를 제공한다.

나는 주로 학습 또는 특정 JavaScript 기능의 브라우저 호환성을 알아보기 위해 사용했었다. 다만 문서를 읽는 중 몇 가지 오탈자가 신경쓰일 때가 있었다. 때로는 문서가 번역되어있지 않아 DeepL로 하나하나 번역하느라 시간을 뺏겼던 적이 있다. 내가 겪은 불편함을 이후에 문서를 볼 개발자도 겪을 거라 생각하니 기여해보고 싶다는 생각이 생겼고, 시간 많은 백수(!)가 된 김에 본격적으로 번역 작업을 진행해보기로 했다.

이 글에서는 mdn의 원문에 기여하는 것이 아닌, 한국어 번역 및 오탈자 수정에 기여하는 방법을 순서대로 설명한다. 기여 방법은 번역 팀의 정책에 따라 변경될 수 있으므로, 공식화된 내용이 필요하다면 한국어 번역 안내서를 참고하는 것을 추천한다.

기여 프로세스

1. 어떤 문서에 기여할지 정하기

번역 오탈자가 발견된 문서나, 미번역된 문서, 더 잘 번역할 수 있을 것 같은 문서를 정한다. 정하고 나서 바로 수정을 시작하는 것보다, mdn/translated-content 레포에서 issue, PR 검색을 해 중복 작업을 피하도록 하자. 보통 PR 이름은 해당 문서의 path로 올라온다.

https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API → /Web/API/Broadcast_Channel_API 로 검색

나의 경우 Broadcast Channel API 관련 문서가 모두 미번역되어 있어서 이 단락을 모두 번역하는 것을 목표로 삼았다.

2. 환경 설정하기

기여한 문서를 로컬에서 확인하고 PR에 반영하기 위해 Node.js, yarn, git이 필요하다.

이를 모두 설치했다면, mdn/content, mdn/translated-content 두 레포를 본인의 GitHub로 Fork하고 Fork된 레포를 로컬에 clone한다. content 레포는 원문과 로컬 환경을 제공하고, translated-content 레포는 번역된 마크다운 파일을 제공한다. 아래는 clone 이후의 폴더 구조 예시이다.

📦 mdn
├─ content
└─ translated-content

추가로, 로컬 환경 구동을 위해 content 레포의 루트 경로에 .env 파일을 생성한다.

# .env

# 본인의 폴더 구조에 맞게 translated-content 레포의 files 폴더 경로를 입력한다.
CONTENT_TRANSLATED_ROOT=../translated-content/files
# VSCode 환경일 때 추가하도록 하자.
EDITOR=code

content 레포의 루트 경로에서 yarn을 실행하고 http://localhost:5042 (또는 터미널에 보이는 포트)로 이동한다.

yarn install
yarn start

이 화면이 나왔다면 로컬 환경 구동이 완료되었다! 최근에 보았던 문서들이 나오고 있는데, 처음 접속했을 때는 보이지 않는 것이 정상이다.

이제 translated-content 레포로 이동해, 작업 내용을 커밋할 브랜치를 생성하고 체크아웃한다 (참고: mdn 번역 팀에서 권장하는 번역 PR의 파일 개수는 1개 이므로 작업 범위를 작게 가져가도록 하자).

여기까지 진행했다면, mdn에 기여할 준비가 완료되었다 🎉

3. 문서 수정하기

오탈자 수정 작업을 한다면 translated-content/files/ko 경로에서 해당하는 문서를 찾아 수정하면 되지만, 미번역 문서를 새로 번역하고자 한다면 content/files/en-us 경로의 원본 문서를 복사-붙여넣기해 진행해야 한다. 번역 시 주의점은 아래와 같다.

이미지 파일은 내부적으로 처리가 되기 때문에, 원본 폴더에 존재하더라도 따로 추가할 필요가 없다. 삭제하도록 하자.
문서 내 링크가 포함된 부분은 한글 문서가 없더라도 한국어 링크(ko)로 변경하자. 자동으로 리다이렉트되도록 처리해준다.
```
['message'](/en-US/docs/Web/API/BroadcastChannel/message_event) ← Bad 👎
['message'](/ko/docs/Web/API/BroadcastChannel/message_event) ← Good 👍
```
번역 용어는 용어 안내서를 우선적으로 참고하자.
제출 전후 yarn lint:md 명령어를 이용해 Lint 에러를 점검하도록 하자. ~~매우 오래 걸린다.~~
문서 상단의 메타 데이터도 수정이 필요하다. (참고: 메타 데이터 안내서)
1. title, short-title, slug, l10n.metadata 외의 내용은 삭제한다.
2. l10n.metadata 는 번역 문서의 최신 상태를 확인하기 위해 사용하는 메타데이터 값으로, 번역 시점의 원본 문서에 마지막으로 반영된 커밋의 해시값을 작성한다. 해시값은 GitHub에서 Fork한 content 레포의 원본 파일을 찾으면 쉽게 알 수 있다. 네모로 표시된 부분을 클릭하면, 해시값이 포함된 URL로 이동한다.
```
l10n:
  sourceCommit: 15d7838061736509d08d642611bd26c1251c0500
```

번역하다 잘 모르는 부분이 있다면 이미 번역된 문서를 참고하거나, MDN Discord #korean 채널 혹은 카카오톡 오픈채팅방(#MDN Korea)에 질문하는 것을 추천한다. ~~굉장히 빠른 속도로 대답해주신다.~~

4. PR 올리기

작업한 내용을 원격 브랜치에 커밋했다면, mdn/translated-content 레포의 GitHub에서 compare across forks를 통해 본인 레포의 작업된 브랜치 기준으로 PR을 올린다. PR 제목은 [ko] prefix를 붙이고, 내용은 작업 내용에 대한 설명과 원문 링크 등을 넣도록 하자.

PR을 올리면, 자동으로 l10n-ko 태그가 붙고, 번역 팀이 리뷰어로 할당되고, 테스트가 실행된다. 테스트 과정에서 오류가 발생하면 보통 원인을 알려주고, 어떻게 변경해야 하는지 댓글로 가이드를 준다. main 브랜치에 반영하기 위해서는 테스트 통과 및 한국어 번역 팀 분들의 Approve가 필요한데, 보통 일주일 이내에 해주시는 것 같다.

리뷰를 기다리는 나의 작고 소중한 PR들….

리뷰를 받으면 디테일한 부분까지 확인해주시는 번역 팀의 노고가 느껴진다. 리뷰받은 사항까지 수정하면 번역 팀 분들이 Approve 후 머지까지 해주신다. 배포되기까지 조금 기다리면, mdn 번역 기여가 완료되었다!

후기

오픈소스 기여에 대해 해보고는 싶지만 내가 그럴 능력이 될까…. 라고 생각해왔었던 것 같다. 지금도 오픈소스의 코드 레벨까지 기여하는 것에 대해선 부담을 느끼지만, mdn 기여를 기점으로 조금 더 자신감을 갖게 되었다. 영어를 특출나게 잘하지 않아도, DeepL 등의 훌륭한 번역 도구가 많이 나와있기 때문에 가볍게 오픈소스 기여를 시작해보고 싶은 개발자에게 추천한다. ~~(영어 실력 향상은 덤)~~

글을 마무리하기 전, 늦은 시간까지 궁금증을 해결해주시고 부족한 번역본을 상세히 리뷰해주신 mdn 한국어 번역 팀에 감사를 전하고 싶다.