[MDN] Markdown 변환 완료 및 앞으로의 방향성

이전 게시물인 [MDN] 11 월 yari-content-ko — 주요 사항에서는 2021년 로드맵, 가이드 문서 개정 등의 내용이 있었습니다. 이 게시물에서는 Markdown 변환 완료 및 Yari Translations Dashboard에 대해서 알아보겠습니다.

Markdown 변환 완료

작년 6월 Converting MDN to Markdown을 시작으로 MDN 문서 Markdown으로 변환 관련 정리 글을 소개했습니다. 그 이후 HTML 형식의 파일들이 Markdown 형식으로 변환되어 왔습니다. 한국의 경우 [ko] Markdown conversion for ko RoadMap를 중심으로 지난해와 올해 동안 약 2400개의 HTML 형식의 파일들이 Markdown 형식으로 모두 변환되었습니다. 다른 locale들도 2022년 11월을 끝으로 모두 변환되었습니다.

따라서, 현재 모든 content repo와 translated-content repo에는 더 이상 HTML 형식의 파일이 남아 있지 않습니다. HTML 형식의 파일을 Markdown 형식으로의 변환이 필요할 경우 Markdown 변환기를 통해 변환할 수 있습니다. 변환 전 git clone 한 repo가 최신 상태인지 확인을 권장드립니다.

대부분의 파일들이 잘 변환되어 문제가 없지만, 몇몇 파일들은 Markdown 변환기가 개발되는 와중에 변환이 진행되어서 잘 변환이 되지 않은 파일들이 있습니다. 따라서, content repo를 기준으로 삼아 Markdown 파일을 비교하며 변환하는 것을 권장합니다.

미사용 macro 제거

이전 Wiki 플랫폼에서 yari로 플랫폼을 옮겨오면서 그 당시 사용한 많은 매크로들이 레거시로 남아 있습니다. 레거시로 남은 매크로를 Kumascript라고 부릅니다. 현재는 yari 저장소 내의 kumascript 폴더로 대체되어 사용되고 있습니다.

아래는 Kumascript의 예시입니다. 해당 매크로들은 더 이상 사용되지 않아야 합니다.

{{Compat("api.Cache.put")}}

MDN의 다음 목표는 더 이상 사용되지 않는 매크로를 제거하거나 형태를 간소화하는 것입니다. Compat 매크로는 현재 아래와 같이 간소화되었습니다.

{{Compat}}

Tracking removal of deprecated macros 에서 전체 macro 제거 현황을 볼 수 있으며, Macro removal - Meta - macros only used in mdn/translated-content에서는 전체 진행 사항을 볼 수 있습니다.

메타데이터 간소화

문서 상단에 있는 메타데이터 또한 간소화되었습니다. title, slug, original_slug, l10n.* 외의 메타데이터는 더 이상 사용하지 않습니다. (참고: #7412)

AS IS

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

TO BE

---
title: Proxy
slug: Web/JavaScript/Reference/Global_Objects/Proxy
---

 

Orphaned and conflicting documents

더 이상 파일이 content repo(en-us)에 존재하지 않거나, 다른 폴더 위치로 이동했을 때 충돌이 발생한 경우 files/<locale>/orphaned 폴더와 files/<locale>/conflicting 폴더 하위에 파일들이 옮겨져 왔습니다. 지속적으로 이런 파일들은 생겨나고 있고, 이러한 파일들을 처리하기 위한 공식적인 지침이 생겼습니다.

Markdown Lint 추가

Markdown Lint 검사를 위한 Github Actions 가 추가되었습니다. 아직 마크다운 린트가 반영된 지 얼마 되지 않아 파일에 추가적인 수정 시 upstream 이슈로 마크다운 린트 오류가 발생하고 있습니다. 오류 발생 시 rebase나 추가 commit을 진행해서 해결할 수 있습니다. Markdown Lint의 경우 자동으로 mdn-bot이 일정 주기마다 자동으로 수정해주는 PR을 생성하고 있어서, 오류를 해결하는데 어려움이 많다면 리뷰어가 그냥 병합해도 괜찮습니다.

translated-content repo에서 yarn markdownlint-cli2 files/ko/파일_경로.md 로 마크다운 오류를 찾아내고, yarn markdownlint-cli2-fix files/ko/파일_경로.md로 자동 수정할 수 있습니다.

Yari Translations Dashboard

번역을 위한 장애물이 많이 사라지고 있습니다. 문서 번역에 집중할 수 있는 환경을 만드는 것이 전체 MDN의 방향성 중 하나입니다.

MDN 문서들을 브라우저에서 볼 수 있게 변환하는 도구 및 페이지를 구성하는 UI 등들이 모두 yari를 통해 작업되고 있습니다. 오늘은 여러 기능 중 Translations Dashboard와 더불어 문서 번역에 도움이 되는 기능들에 대해서 소개드립니다.

yari 설치하기

git clone https://github.com/mdn/yari.git && cd yari && nvm use && yarn install

yari 폴더 하위에 .env 파일을 추가해줍니다. VSCode를 사용할 경우 EDITOR=code 를 추가해주면 yari 플랫폼에서 바로 VSCode로 연결할 수 있습니다. 또한, SERVER_PORT 옵션을 통해 서버 상용 포트를 지정할 수 있습니다.

# .env 파일

CONTENT_TRANSLATED_ROOT=/Users/<PATH_TO_TRANSLATED-CONTENT>/translated-content/files
CONTENT_ROOT=/Users/<PATH_TO_CONTENT>/content
EDITOR=code
SERVER_PORT=5042

yari를 실행하면 기본적으로 3000 포트와 5042 포트로 페이지가 제공됩니다. 이때, 3000 포트는 서버 개발 포트, 5042 포트는 서버 상용 포트입니다. 개발 서버에서는 문서 번역에 도움이 되는 기능들을 사용할 수 있으며, 상용 서버에서는 실제로 배포된 MDN 페이지를 확인할 수 있습니다.

yarn dev
open http://localhost:5042

yarn start 를 더 선호하면 이전에 컴파일된 파일들을 재사용하는 yarn start도 사용할 수 있습니다. 조금 더 위험성이 높지만 빠릅니다. yarn dev 는 항상 모든 것들을 최신 상태로 유지해서 안전합니다.

yarn start 명령어는 약간 다른 동작으로 서버를 시작합니다. 소스 코드 파일이 변경될 때 자동으로 다시 로드되지 않으므로 주의해서 사용해야 합니다.

yarn start 명령어 실행 시 popularities.json 파일이 없어서 오류가 발생하면, 아래 명령어로 popularities.json 파일을 생성할 수 있습니다.

yarn tool popularities

 

Home

http://localhost:5042/ko/

상기 URL로 접근하면 MDN의 메인 Home 페이지를 볼 수 있습니다. (https://developer.mozilla.org/ko/)

Translation Dashboard

http://localhost:3000/ko/_translations/dashboard

Translation Dashboard에서는 현재 한국의 대략적인 MDN 전체 문서 번역 현황을 파악할 수 있습니다. 정식적으로 제공되는 기능은 아니기에 아직 부족한 요소가 많지만, 많은 정보들을 얻을 수 있으므로 참고하면 좋습니다.

Translation Missing

http://localhost:3000/ko/_translations/missing

Translation Missing에서는 en-us 페이지와 비교해서 번역되지 않은 페이지들에 대해 Popularity가 높은 순서대로 확인할 수 있습니다. Popularity는 조회수 순위입니다. 모든 페이지에 대해 완벽할 수 없으므로, 기여 시 조회수가 높은 페이지들을 먼저 번역하는 것을 추천드립니다.

Flaws

http://localhost:3000/ko/_flaws

Flaws에서는 각 페이지에 대해 결점들을 확인할 수 있습니다.

예를 들어, 첫 줄에 보이는 Learn 페이지에 2개의 결점이 있는 것을 볼 수 있습니다.

http://localhost:3000/ko/docs/Learn

Learn 페이지에 접근한 후, 아래 빨간 상자 영역에서 Show flaws를 클릭해서 해당 페이지의 결점들을 확인할 수 있습니다.

Sitemap

http://localhost:3000/ko/_sitemap

Sitemap에서 사이트 맵 또한 확인할 수 있습니다.

리뷰어 모집

리뷰어들이 기여자분들께 항상 꾸준하게 좋은 경험을 드리는 것은 어렵다는 것을 지난 1년 동안 느꼈습니다. 더 나은 리뷰 경험을 드리기 위한 회의에서 추가적인 리뷰어를 모집하는 것이 좋겠다는 결론을 내렸습니다. 또한, 기여가 힘든 상황에 있는 리뷰어들을 위해 잠시 휴식 기간을 보장받을 수 있도록 분기마다 순환할 수 있는 방안도 마련할 예정입니다.

기존에 MDN에 기여를 많이 해주시는 분들께도 기회가 가도록 공정하고 공개적으로 리뷰어를 모집하고, 추후 리뷰어들이 지속적으로 유지될 수 있도록 몇 가지 기준을 정했습니다.

모집 및 운영

• 1차 모집: 2022년 12월 31일까지 지원
• 이메일: hochan049@gmail.com
• 1차 모집 이후에는 리뷰어 지원은 항상 열려있되, 기여 현황 파악 후 기존 리뷰어들 모두와 공유 후 결정. 반기에 한 번씩 일정 주기마다 리뷰어 승인을 하며, 리뷰어 승인 기간 외에 지원은 보류 => 이후 추가 모집시 추가적인 공고로 모집.

기준

• 번역 경험을 우선적으로 보고 PR 현황이나 yari 경험 우대
  • 지원 시 https://github.com/mdn/translated-content/commits?author=[깃허브 아이디] 링크를 같이 메일에 첨부 부탁드립니다.
• 1차 모집 시에는 translated-content 기여도가 높은 순서대로 개인적으로 리뷰어 요청 이메일을 드릴 예정

 

마치며

주신 피드백들을 바탕으로 더 나은 기여 환경을 만들 수 있도록 노력하겠습니다. 좋은 의견 있으시면 깃헙 이슈로 올려주시거나 오픈 톡방/ 댓글로 언제든지 알려주세요. MDN 관련 의견들은 MDN Web Docs Discussions 에서 확인하거나 토론하실 수 있습니다.

감사합니다.

모두 좋은 하루 보내세요 :)

https://github.com/mdn/translated-content

GitHub - mdn/translated-content: All translated MDN content in raw form