🎯 MDN Web Docs 기여 방법에 대해 정리합니다.

📗 Today I Learned

MDN Web Docs 번역 기여

오픈 소스에 기여하기 좋은 프로젝트 중 하나인 MDN Web Docs의 번역 기여 방법을 정리하였습니다.

👉 MDN 한국어 번역 콘텐츠 안내서

1. MDN 한국 문서 중에 번역이 필요한 문서 찾기

한국어 페이지와 영어 페이지를 비교하면서 번역이 안 된 부분이나 오타를 찾습니다.

• MDN 한국 문서

• MDN 미국 문서

2. GitHub 저장소 Fork & Clone

다음 두 개의 저장소를 Fork한 후 로컬로 clone합니다.

• content : 원문(en-US) 콘텐츠가 있는 저장소입니다.
  (번역 기준이 되는 원문을 확인하기 위해 clone합니다.)

• translate-content : 번역된 콘텐츠가 있는 저장소입니다. 실제 작업과 PR은 이 저장소에서 이루어집니다.

git clone https://github.com/[본인 github ID]/translated-content
git clone https://github.com/[본인 github ID]/content

🤔 한 파일(한 디렉토리 내에서) 두 개의 Git 저장소를 클론해도 될까?

git clone https://github.com/사용자명/저장소명

clone 명령어를 실행하면 GitHub에 있는 URL로 지정한 저장소 전체를 복사해오고, 현재 디렉토리를 기준으로, 저장소 이름과 동일한 새 폴더를 생성해서, .git/ 디렉토리를 포함한 전체 Git 히스토리 + 파일 구조를 생성합니다.

---

💡 지금 경우에는 현재 디렉토리에 translated-content/와 content/라는 두 개의 폴더가 생기고, 각각은 독립된 Git 저장소이기 때문에 한 파일 내에 두 개의 저장소를 클론해도 됩니다.

📂 현재 작업 디렉토리/
├── 📁 translated-content/
│   └── .git/  ← 첫 번째 저장소의 Git 정보
└── 📁 content/
    └── .git/  ← 두 번째 저장소의 Git 정보

3. 번역 저장소에서 브랜치 생성

이제 번역 저장소(translated-content)로 이동해서 작업 브랜치를 생성합니다.

cd translated-content
git checkout -b [comment]
# 예: git checkout -b ko_fix_typo_array_doc

4. .env 파일 생성 및 환경 변수 설정

content 저장소로 이동해서 .env 파일을 content 폴더 내부에 생성합니다.

cd ../content

📂 현재 작업 디렉토리/
├── 📁 translated-content
├── 📁 content
|   ├── .github
|   ├── files
|   ├── pr-lint
|   ├── rfcs
|   ├── scripts
|   ├── .editorconfig
|   ├── .env       <==== content 폴더 내부에 만들어준다.
|   └── ...
└── ...

.env 파일에 아래 내용을 추가합니다.

CONTENT_TRANSLATED_ROOT=[파일경로]/translated-content/files
EDITOR=code

.env 파일을 생성하지 않으면 번역된 콘텐츠와 연동되지 않으므로 반드시 작성해야 합니다.

5. 의존성 설치 및 로컬 서버 실행

content 저장소의 루트 디렉토리에서 yarn 명령어로 패키지를 설치하고 서버를 실행합니다.

yarn install
yarn start

정상적으로 실행되면 http://localhost:5042/ko/ 로 접속할 수 있습니다.

6. 원하는 페이지로 접속합니다.

로컬 서버가 실행된 뒤, 번역하고 싶은 문서로 접속합니다.

7. 문서 수정

수정은 두 가지 방법 중 선택할 수 있습니다.

• Open in your editor : VSCode로 자동 열기 (.env에 EDITOR=code 설정한 경우)

• Quick-edit : 브라우저 내에서 간단하게 텍스트 수정

8. 커밋 및 PR 생성

수정이 끝나면 커밋을 해주고 내 깃허브 장소로 push를 보냅니다.

git add .
git commit -m "fix: 한국어 번역 오타 수정 - React getting started"
git push origin [브랜치 이름]

GitHub 저장소에 들어가 Contribute > Create pull request를 클릭하여 PR을 생성합니다.

💡 PR 생성 시 Create pull request 버튼 옆에 있는 Allow edits by maintainers를 활성화해야 합니다.

---

이슈와 PR 연결

GitHub에서는 PR을 생성할 때 이슈를 자동으로 연결할 수 있습니다. (#이슈번호)

이슈 게시판

프로젝트의 작업, 개선사항, 버그 제보 등을 위한 게시판입니다.

• 담당자, 라벨 등을 이용해 분류 가능
  

아래처럼 작성하면 PR이 머지될 때 해당 이슈가 자동으로 닫힙니다.

• closed #이슈번호

• fixed #이슈번호

• resolved #이슈번호

• 자세한 공식 문서 : GitHub Docs - Linking a pull request to an issue

---

✏️ 회고

번역 기여에도 고려해야 하는 사항이 많고 기여하는 과정이 처음엔 다소 복잡하다고 생각할 수 있을 거 같다.