MDN 문서 번역을 통해 오픈 소스 기여를 경험해보자

MDN의 HTML <menu> Element 번역을 통해 오픈 소스 기여 첫걸음을 내딛어봅니다.

•8 min read•
views

오픈 소스에 기여해보고 싶다는 생각이 문득 들었다. 어떻게 하면 작게 맛을 볼 수 있을까 생각해보았는데 곧바로 MDN이 떠올랐다. 실행을 해보았고, 리뷰어의 친절한 지도 덕분에 첫 번역을 완료할 수 있었다.


metacode22 계정이 MDN에 기여한 모습

MDN에는 아직 한국어로 번역되지 않은 문서들이 많이 있다. 언어를 한국어로 설정하고 여러 페이지를 돌아다니다보면 Page not found가 자주 뜨는 것을 확인할 수 있다.

strong 태그의 경우 한국어로 번역되지 않아 뜨게 되는 page not found

이렇게 Page not found가 뜨는 것들 중에서 menu 요소를 번역해보았다. 양이 적어서 처음 해보기에 적당하다고 판단했기 때문이다. 짧지만 오픈 소스에 처음 기여해보는 경험이 뜻 깊었기에 과정과 약간의 팁을 소개해보려 한다.

번역 방법

  1. 개발(번역) 환경 세팅

MDN 사이트는 크게 2가지의 레포를 통해 배포되어 있다. 영문의 원본 컨텐츠가 담긴 mdn/content 레포와 이를 번역한 컨텐츠가 담긴 mdn/translate-content 레포이다. 이 2개의 레포를 fork 해주자. 그리고 fork된 레포를 로컬로 clone 해주자.

이제 로컬의 mdn/content 레포에 들어가 루트 디렉토리에 .env 파일을 생성한다. 그리고 다음 코드를 삽입하자.

CONTENT_TRANSLATED_ROOT=/path/to/translate-content

mdn/translate-content가 로컬의 어디에 위치해있는지 나타내는 경로이다. 이 때 주의할 점은 상대경로가 아니라 절대경로를 입력해야 한다는 점이다. mdn/translate-content가 위치해 있는 곳에서 터미널에 pwd라는 명령어를 입력해주자. mdn/translate-content의 절대경로를 손 쉽게 알아낼 수 있다.

이후 content 레포에서 yarn install, yarn start 명령어를 차례대로 터미널에서 실행하여 개발 서버를 실행시킨다.

  1. 번역

개발 환경이 마련되었으니 번역을 진행해보자. 번역은 mdn/translate-content 레포에서 진행된다. 이 레포의 main 브랜치에서 본인이 하고자 하는 작업 내용에 맞게 브랜치를 생성해주자.

번역에 있어서 2가지의 경우가 존재할 수 있을 것 같다. 이미 존재하는 번역본의 오타 등 잘못된 내용을 수정하거나, 번역이 안 되어 있어 새로 파일을 만들어 번역을 진행하는 경우이다.

  • 이미 존재하는 번역본 수정하기

번역본이 어디에 존재하는지부터 알아보자. 1단계를 그대로 실행했다면, 브라우저에서 localhost:5042로 접속 시 mdn 개발 서버를 확인할 수 있다.

menu 요소의 번역본을 수정한다고 가정해보자. 개발 서버에 한국어로 번역된 menu 요소 문서를 찾아 접속해보면 url이 다음과 같을 것이다.

http://localhost:5042/ko/docs/Web/HTML/Element/menu

localhost:5042 뒤의 경로를 mdn/translate-content 레포의 files라는 폴더에서 찾으면 된다. 지금과 같은 경우는 다음과 같이 files/ko/web/html/element/menu/index.md가 되겠다.

mdn/translate-content 레포에서 menu 요소 번역 파일의 위치
  • 번역 문서 만들기

이번에 진행했던 menu 요소 번역이 번역 문서를 만든 경우이다. 즉 한국어로 번역된 문서가 존재하지 않았다.

별다른 어려움은 없다. 영문 문서의 경로에서 en-US만 ko로 바꾼 경로에 번역할 마크다운 파일(index.md)을 만들면 된다. 즉, /en-US/docs/Web/HTML/Element/menu라면 /files/ko/docs/web/html/element 폴더에서 menu 폴더를 만든 후 그 폴더에 index.md 파일을 만들어서 번역을 진행하면 된다.

  1. Pull Request 및 리뷰

수정 혹은 번역이 완료되었다면 해당 branch를 push하고, 원본 레포에 PR을 생성한다. PR을 생성하고 나면 mdn의 자체 linter가 돌아가면서 1차적으로 어떠한 것을 고쳐야 하는지 알려준다.

mdn linter가 1차적으로 코드를 검열해준 모습

리뷰어는 라운드 로빈 방식에 의해 자동으로 할당된다. 해당 리뷰어와 논의를 거쳐 수정이 필요하다면 수정하고, approve를 받아 merge하면 된다.

참고로 나는 리뷰어의 리뷰가 늦어지는 감이 있어, 자주 활동하시는 분에게 메일을 보내 따로 리뷰를 요청했었다. 만약 이러한 경우를 겪게 된다면 나와 같이 다른 리뷰어에게 리뷰를 요청해보자.

[ko] translate: menu



팁

  • GPT

꽤나 GPT(4.0)가 번역을 잘해준다. GPT가 번역해준 것을 검토하고 수정하면 많은 시간을 아낄 수 있다. 다음은 내가 GPT를 이용할 때 입력한 프롬프트의 일부이다.

... 영문으로 작성된 menu 요소 마크다운 파일 ...
 
이건 <menu> 태그에 대해 설명하는 영문의 mdn 문서야.
 
이걸 ko, 즉 한국어로 번역해서 mdn repository에 pull request를 보내려고 해. 기여하고 싶어서.
 
이런 목적에 맞게 한국어로 번역해줘.
  • sourceCommit

metadata에 sourceCommit 정보를 넣어야 한다. 이는 내가 번역할 당시, 원본 레포(mdn/content)의 내가 번역 혹은 수정하고자 하는 파일의 가장 최신 commit hash 값을 말한다. 번역할 당시 원본 레포의 해당 컨텐츠가 어떠한 내용을 담고 있었는지 파악하기 위함이다.



참고