[오픈소스] 나름 친절한 MDN 번역 기여 가이드(24.04 ver)

(이 가이드는 vs 코드를 사용했을 때를 기준으로 설명합니다. + git 관련 기본 지식이 있는 독자를 대상으로 합니다.)

들어가면서

며칠 전 MDN 공식 문서 한국어 번역에 기여했다.

해당 PR

공식 가이드가 잘 구성되어있어서 큰 어려운 점은 없었지만, 좀 더 A to Z 까지 자세하게 설명하는 가이드가 있으면 좋겠다는 마음에 이 글을 작성하게 되었다.

아직도 한국어로 번역되지 않은 부분들이 많다. 관심 있는 영역이 있고, 해당 부분이 아직 번역되지 않은 상태라면 한국어 번역에 참여할 절호의 기회다!

번역작업에 들어가기 전 참고해야할 문서 정리

내가 어떻게 했는지 아래에서 자세히 설명할 것이지만, 우선 번역 작업을 들어가기 전 참고해야 할 문서들을 정리해본다.

MDN 코리아 공식 기여 가이드

• 위 README.md 문서는 번역 규칙 관련 꼭 참고해야할 가이드에 대한 설명을 포함하고 있다. 따라서 숙지하는 것이 좋다.
• 여러 안내서가 있는데 번역 안내서, 용어 안내서는 반드시 옆에 펼쳐놓고 번역 작업을 하자.
• 메타 데이터 안내서와 관련해서는 아래에서 자세히 설명한다.

MDN 기여 가이드 라인

• 위 문서가 생기기 전에 만들어진 비공식 가이드라인이나, 나는 이 가이드라인을 참고하여 아주 순조롭게 기여할 수 있었다. 그 정도로 내용이 상세한 편이다.

먼저 작업대를 내 컴퓨터에 가져옵니다.

영어 원문이 있는 레포지토리와 번역된 컨텐츠들이 있는 레포지토리 각각에 모두 들러서 각 레포지토리를 fork한다. 그리고 fork한 레포지토리를 내 컴퓨터에 git clone 한다.

그리고 내 컴퓨터에서 translated-content 폴더에 들어간 다음 브랜치를 하나 파 준다.

git checkout -b [내가 기여할 사항과 관련된 브랜치 네임]

그런 다음 translated-content 폴더에서 잠깐 빠져나와 영어 원문이 있는 content 폴더로 간다.

그리고 content 폴더 루트에 .env 파일을 생성해준다.

그리고 해당 .env 파일에 다음 옵션을 작성한다.

CONTENT_TRANSLATED_ROOT=[얻는 방법은 바로 다음에 설명. .env 파일에 translated-content repo 경로를 설정해주는 것.]
EDITOR=code

CONTENT_TRANSLATED_ROOT 값은 vs 코드에서 translated-content를 열고 files 폴더를 찾은 다음, 오른쪽 마우스를 클릭하여 'Copy Path'를 통해 얻으면 된다.(상대 경로가 아닌 절대경로여야 한다!)

나의 경우 다음과 같이 .env 파일을 설정했다.

CONTENT_TRANSLATED_ROOT=/Users/[username]/mdn/translated-content/files
EDITOR=code

content를 실행시킵니다.

content는 실행시킬 수 있다. 즉, files 내부의 마크다운 파일들(mdn의 콘텐츠들)이 실제 mdn에서 어떻게 보여지는지 미리 볼 수 있다. 이를 이용하면, content를 통해 번역을 해보고, 그 번역 결과가 실제로 어떻게 사이트에 반영이 되는지 실시간으로 확인해볼 수 있다.

content를 실행시키는 방법은 간단하다. 우선 yarn을 설치하자.

그런 다음, content 폴더에서 다음 명령어를 실행시킨다.

yarn install
yarn start

그런 다음, 브라우저로 들어가 localhost:5042를 입력하면, mdn 페이지 미리보기가 떠 있는 것을 알 수 있다.

주소창을 주목하라. 난 지금 '/docs/Web/API/Contact_Picker_API에 와있다. vs 코드에서 files/web/api/contact_picker_api/index.md에 가봐라. 가서 아무 문장이나 편집해봐라.

저기 하찮은 '안녕하세여?'에 주목. 편집한 사항을 바로바로 볼 수 있는 것을 알 수 있다.

메타데이터를 수정합니다.

번역하고 싶은 문서를 찾았다면, 가장 먼저 해야할 일은 수정하고픈 index.md 파일의 메타데이터를 수정하는 일이다. 공식 기여 가이드에 다음과 같이 명시되어있다.

문서의 상단에 있는 메타데이터는 title, short-title, slug 그리고 l10n.*만 사용합니다

• 메타데이터란? md 파일에서 최상단에 '---' 사이에 적혀있는 것.

영어 원문의 메타데이터는 보통 다음과 같이 기술되어있다.

---
title: Proxy
slug: Web/JavaScript/Reference/Global_Objects/Proxy
tags:
  - Class
  - ECMAScript 2015
  - JavaScript
  - Proxy
- browser-compat: javascript.builtins.Proxy
---

{{JSRef}}

The `Proxy` object enables you to create a proxy for another ...
:

여기서 다른 거 다 빼고, 다음과 같이 작성하라는 뜻이다.

---
title: Proxy
slug: Web/JavaScript/Reference/Global_Objects/Proxy
l10n:
  sourceCommit: 2eb202adbe3d83292500ed46344d63fbbae410b5
---

{{JSRef}}

**`Proxy`** 객체는 기본적인 동작(속성 접근, 할당, 순회, 열거, 함수 ...
:

여기서 한가지 의문이 들 것이다. 'title이나 slug는 원문에도 있으니까 그냥 그대로 가져오면 되는데, l10n, sourceCommit은 뭐야?'

이것에 대해선 공식 가이드가 다음과 같이 설명하고 있다.

번역된 문서가 en-US 문서에 대해 얼마나 뒤쳐져 있는지 알 수 있는 마땅한 방법이 없습니다. l10n.sourceCommit 메타데이터를 추가하여 현재 문서가 명시된 en-US의 hash 까지 최신 상태를 유지하고 있음을 나타낼 수 있습니다. (참고: How to indicate "content parity" of localized documents vs en-US counterparts?)
sourceCommit: 기여하는 문서와 동일한 en-US 문서의 가장 최신 40자리 hash를 명시합니다. (예: slug: Glossary/Array 문서에 대해 기여할 때, content 저장소의 slug: Glossary/Array 문서에서 가장 최신 40자리 hash를 명시합니다.)
주의: content 저장소의 가장 최신 hash가 아닌, content 저장소에서 기여하는 문서와 동일한 위치의 파일에 대한 hash 입니다.

즉, 버전의 추적을 용이하기 위해서 만들어놓은 장치인 것 같다. sourceCommit의 value에 해당하는 hash를 가져오려면,

일단 영어 원문 깃헙 저장소로 간다. 그리고 내가 편집할 문서가 있는 곳까지 간다. (일단 내가 번역에 기여한 cookie store api를 예로 들겠다.)

커밋 메시지 옆에 저기 '2c64120'가 커밋 고유 해시 번호를 의미한다. 물론 커밋마다 다 다를 것이다. 저기를 클릭한다.

그 다음, 주소창에서 40자리 hash를 긁어와 복붙하면 된다. commit/ 옆에 있는 저 긴 숫자+문자가 해시번호다.

결과:

---
title: Cookie Store API
slug: Web/API/Cookie_Store_API
l10n:
  sourceCommit: 2c641e08878722bf29fb784d58c61873ce4a133a
---

편집하면서, 번역된 결과를 실시간으로 봅니다.

여기까지 끝났다면, 이제 번역 작업을 하면 된다.

쉽게 하는 방법은 다음과 같다. mdn 페이지 미리보기 화면을 띄운 후 deepL 크롬 익스텐션을 깔아서 번역 결과를 본다. 그리고 그것을 복사해서 index.md에 붙여넣고, 공식 가이드에 맞게 단어들을 수정하고, 좀 더 자연스럽게 문장을 다듬어나간다. 그리고 번역된 결과를 살펴본다.

물론 가이드를 꼼꼼히 읽었다면 알겠지만, 번역 작업에는 몇 가지 주의해야할 사항들이 있다.

• '개념 및 사용법', '명세서' 등 이러한 큰 제목들은 다 통일이 되어있다. 관련해서는 공식 가이드에 잘 나와있다. 큰 제목 외, 문서에서 사용되는 용어의 번역에 관해서도 주의해야 할 점이 있으니 꼭 가이드를 참고하여 숙지하길 바란다.
• index.md를 보다보면 {{...}}로 감싸진 뭔가를 볼 수 있을텐데 이것을 매크로라고 하는 모양이다. 내부 코드와 연동해서 작동하는 것 같은데, 내부 코드와 관련이 있으므로 털 끝 하나도 건드리지 않는 것이 좋다.
• ':', ";', italic 체 사용 등, 한국어 맞춤법과 맞지 않는 표기는 지양하고 있다. 이와 관련해서도 공식 가이드에 잘 나와있으니 꼭 살펴보길 바란다.
• 링크 첨부는 보통 영어 원문에서는 '/en-US/docs/Web/API/Service_Worker_API' 이런식으로 되어있을텐데 이러한 링크 첨부는 전부 '/ko/docs/Web/API/Service_Worker_API'로 바꿔라. 이와 관련된 내용도 전부 가이드에 나와있다.

그 외 여러가지 주의해야 할 사항은 전부 가이드에 나와있으니 참고 바란다.

잘 모르겠다면 남이 한 것을 눈치껏 살펴봅니다.

이것은 팁 아닌 팁인데, 가이드를 읽어봐도 잘 모르겠거나 애매한 부분이 있을 수 있다. 이때는 translated-content로 들어가 남이 한 것들을 살펴보며 어떻게 해야하는지 알아가면 된다.

그래도 모르겠거나 여전히 애매하다면, 공식 채널(디스코드 등)이 있으니 반드시 그곳에 문의하도록 하자.

번역이 된 것을 translated-content로 가져옵니다.

번역 작업이 끝났다면 다시 translated-content로 돌아온다. (이 때 터미널을 켜서 브랜치를 잘 확인하길 바란다.)

그리고 vs 코드를 켜서 files/ko/ 아래에 정확히 영어 원문 콘텐츠가 있었던 위치에 index.md를 추가한다.

나의 경우, cookie store api는 영어 원문에서 files/web/api/cookie_store_api에 있었으므로 정확히 files/ko/web/api/cookie_store_api 아래에 index.md를 추가해줬다. cookie_store_api 폴더가 기존엔 없었으므로 폴더를 추가하고 안에 index.md를 추가해줬다.

그리고 content에서 번역한 내용을 복사하여 translated-content에 붙여넣기한다.

그리고 커밋을 한 뒤, git push [branch-name]를 하고, fork했었던 translated-content로 간다.

• 커밋 메시지는 보통 앞에 '[ko]' 라는 머릿말을 달고 영어로 작성하는 것 같다.

PR을 날리고 리뷰를 기다립니다.

PR을 날리기 전, 다음 규칙을 숙지했는지 먼저 확인하자.

ko-locale에 존재하지 않는 새로운 파일에 대한 번역을 진행할 때, 파일 전체 번역 을 원칙으로 합니다. (단, CORS 와 같이 분량이 많은 파일에 대해서는 부분 번역을 허용합니다. 이때, 번역되지 않은 부분은 en-us locale 원본으로 대체합니다.)

PR의 Merge 우선 순위는 관련 이슈에서 가장 처음 언급된 PR이 병합 우선권을 갖습니다. 리뷰어는 우선 순위가 있는 PR을 먼저 병합하는것을 원칙으로 합니다. 따라서, 번역을 진행하기 전에, PR과 관련된 이슈가 없다면 이슈를 생성하는 것을 권장합니다. ko-locale PR 목록

위 규칙들로 우선 순위를 정하기 힘든 경우 리뷰어는 기여자에게 충돌 해결을 요청 드릴 수 있습니다. 이 경우에는 충돌 해결 후 병합을 진행합니다.

그리고 PR을 날리면 된다.(PR 날리는 법에 관해서는 생략하겠습니다.)

allow edits by maintiners는 반드시 체크한 상태로 두자.

그러면 github action이 불나게 돌아가기 시작하는 걸 볼 수 있는데, 잘못 건드린 게 없는 이상 정상적으로 돌아갈 것이다.

다만 다른 건 다 완료가 되고 이건 완료가 안될 수가 있는데,

딱히 신경 쓸 필요는 없는 것 같다. 아마 merge가 됐느냐, 안됐느냐와 연관이 있지 않을까 싶다.

그리고, 이렇게 PR을 날렸는데 얼마 있다가 translated-content에 내가 아닌 다른 누군가의 새 PR이 merge가 되는 경우가 있는데, 이렇게 되면 내 PR의 최신 커밋이 outdated가 된다. 그러면 github action에서 액션을 취하라는 안내문구가 뜨는데,(두 가지 선택사항이 있다) 나는 이런 경우에는 보통 rebase를 선호해서 rebase를 선택했다.

리뷰에 맞춰 수정하고 다시 리뷰를 요청합니다.

얼마 기다리면, 리뷰어분이 와주시며, 세세하게 리뷰를 해주신다. 그 수정사항 요청에 맞춰 수정하고 다시 커밋을 달리면 된다. 그리고 오른쪽에 reviewers를 보면 버튼(?)이 있는데 그 중 마우스를 가져다 댔을 때, '리뷰 재요청하기'라는 문구가 뜨는 버튼을 클릭한다.

해당 버튼이 있는 자리

승인을 받았다면 Merge 되기를 기다립니다.

리뷰를 받았고 그에 맞춰 수정까지 완료했으며 승인까지 받았다면 이제 가만히 Merge 되기를 기다리면 된다.

주의사항

컨텐츠에 따라 나와 약간은 다른 절차를 밟아야할 수도 있다. 100% 정확하지 않을 수 있는 가이드이니, 반드시 공식 가이드를 참고하자. 앞서 언급했지만 만약 가이드에도 나와있지 않다면 다른 사람이 번역한 부분을 참고해보자. 그래도 잘 모르겠거나 애매하다면 공식 채널(디스코드 등)이 있으니 그곳에 문의해보자.

그럼 모두들 화이팅

틀린 내용, 혹은 오해를 불러일으킬만한 내용이 있다면 바로 댓글로 정정해주시길 부탁드립니다!