[MDN] 7 월 yari-content-ko — 주요 사항

이전 게시물인 [MDN] 6 월 yari-content-ko — 주요 사항과 향후 계획에서 Markdown에 대한 언급이 있었습니다. 2021년 7월 27일 현재 translated-content에서 해당 PR을 기준으로 공식적으로 Markdown을 사용 가능하게 되었습니다. 이제 translated-content에서 Markdown으로 작성 가능하고, MDN도 Markdown 작성을 지향합니다. 이 게시물에서는 7월 MDN 주요 사항들에 대해서 알아보겠습니다.

 

MDN 문서 Markdown으로 변환

Yari 이전에는 MDN 문서는 WYSIWYG 편집기에서 편집되었으며, 페이지를 HTML로만 편집할 수 있는 옵션이 있었습니다. Yari 이후로는 MDN 문서를 텍스트 편집기에서 HTML로만 편집할 수 있습니다.

 

현재, 이 방식은 느리고 더 어려우며 더 많은 형식 오류가 발생합니다. 작성자는 표현하고자 하는 내용 대신에, 항상 형식에 대해 신경 써야만 했습니다. 이로 인해, 문서의 질은 나빠졌습니다. 또한, HTML에 익숙하지 않은 사람들은 형식의 복잡성으로 인해, 기여하기에 어려움이 많았습니다.

 

마지막으로, 검토하는 데에도 많은 어려움들이 있습니다. 

 

HTML로 작성된 Table 요소

Markdown으로 작성된 Table 요소

이에 대한 해결책으로 MDN 문서를 Markdown으로 마이그레이션하는 제안이 나왔고, content 저장소를 시작으로 현재 translated-content 저장소에서도 Markdown을 작성할 수 있게 되었습니다.

 

MDN관련 Markdown의 세부사항은 아래 링크를 참고해주세요.

https://egas.tistory.com/64?category=482046 

MDN to markdown conversion

 

사용법

 

처음 시작하시는 분들은 MDN 번역 콘텐츠에 대한 일반 지침을 먼저 참고해주세요. HTML에서 Markdown로의 변환은 yari의 새로운 추가 기능입니다. yari에서 아래 명령어로 변환할 수 있습니다. (해당 명령어를 실행하면 html 파일이 있는 경로에 md 파일이 생성됩니다.)

yarn md h2m web/javascript/path --locale ko --mode keep

 

• h2m: html에서 markdown으로의 변환을 의미하며, markdown에서 html로의 변환 기능도 존재합니다.
• web/javascript/path: translated-content 저장소에서 변환하고자 하는 파일의 폴더 경로를 의미합니다.
• --locale: 로케일을 의미하며, 한국의 경우 ko입니다.
• --mode: dry, replace, keep 3가지 option이 있지만, 한국의 경우 완벽한 변환을 기대하기 힘듭니다. 따라서, html, md 문서 모두 비교할 수 있는 옵션인 keep 옵션을 사용해서 비교하는 것을 추천합니다.

다음과 같은 .env 파일을 yari의 root 경로에 추가해야, yari가 content와 translated-content를 clone 한 저장소의 위치를 추적할 수 있습니다. 자세한 내용은 MDN 번역 콘텐츠에 대한 일반 지침 참고.

 

//.env
CONTENT_TRANSLATED_ROOT=/Users/PATH/TO/translated-content/files 
CONTENT_ROOT=/Users/PATH/TO/content 
EDITOR=code

 

주의사항

yari 변환 기능의 변환 조건이 엄격해서 변환이 안 되는 부분들이 많습니다. yarn md h2m web/javascript/path --locale ko --mode keep 명령어로 모두 해결되면 좋겠지만, 많은 한국 문서에 레거시로 인해 변환이 잘 이뤄지지 않는 경우가 많습니다. (예: id, class 값이 있을 경우 변환을 하지 않고 그대로 놔둠). 따라서 명령어를 통한 변환 후에, 추가적인 검토가 필요합니다.

 

주의사항

`존재하는 파일에 대한 변경 (존재하는 파일이 .html 확장자일 경우)`에 대한 경우, Git History 유지를 위해 확장자만 먼저 .html에서 .md로 변경한 후 commit을 하는 과정을 반드시 진행해야합니다. 아래 가이드라인을 꼭 참고해주세요.! (참고: `git log --follow (파일)` 로 해당 파일의 git history를 볼 수 있습니다.)

 

git log --follow (파일)

 

https://github.com/mdn/translated-content/pull/1773/files

[ko] markdown guideline by hochan222 · Pull Request #1773 · mdn/translated-content

 

번역 우선 순위

 

content 저장소는 7월 중순에 /web/javascript 폴더 내의 있는 파일들의 대해 변환을 모두 마쳤습니다. MDN은 각각의 locale에 대해 content 문서를 참고해서 /web/javascript 폴더 내의 있는 파일들을 우선적으로 변환하는 것을 권고합니다. 자세한 사항은 다음 링크를 참고해주세요.

 

시범적으로 /web/javascript 폴더 내의 아래 파일들에 대하여 변환을 마무리했습니다.

• a_re-introduction_to_javascript
• about_javascript
• closures
• data_structures
• enumerability_and_ownership_of_properties
• equality_comparisons_and_sameness
• eventloop

관련 세부사항은 아래 링크를 참고해주세요.

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

[ko] convert html to markdown (1) /web/javascript by hochan222 · Pull Request #1698 · mdn/translated-content

 

권고사항

PR 간의 충돌을 최소화하기 위해 Github Draft를 먼저 작성한 뒤 작업해주세요.

 

가이드라인 추가 반영 사항

번역 가이드에 현지화 과정에서 충돌/고민이 많은 단어들에 대해 계속 수집하고 정리할 예정입니다. 

 

앞서 6월 소식지에서도 언급했듯이, 해당 가이드 완성에 대한 노력은 계속됩니다. 번역 가이드 작성에 있어서 아래와 같은 사항들이 있었습니다.

• Javascript 용어집: 기존에 혼동이 많았던 JS 용어들에 대해 기준 가이드라인이 추가됐습니다. (참고 링크)
• 역자/역자주: 그동안의 MDN 문서에서는 역주로 인한 자의적인 해석이 많았고, 전체적인 문서의 품질을 낮췄습니다. 역주가 꼭 필요한 상황이 아니라면 역주는 남기지 않으며, 남기더라도 따로 역주를 표시하지 않고 본문에 포함합니다. (예시 및 참고 링크)

 

추가적으로, 단어 관련해서 통일하고 싶은 사항이 있으면 아래 이슈에 남겨주세요.

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

[ko] Establishing basic Korean vocabulary guidelines · Issue #1631 · mdn/translated-content

 

변경 사항

 

7월에도 많은 이슈들이 있었습니다. 너무 많아 모든 이슈들을 정리하지는 못하겠지만, 경험 공유를 위해 팀이 경험한 주요 이슈들을 요약정리했습니다.

 

전체 사항

• delete conflicting/orphaned in ko
  • 2021년 초 봄부터 conflicting/orphaned 문서들에 대해 인덱싱 하지 않고 저장소에 남겨두기로 결정했습니다. 하지만, 이러한 문서는 더 이상 Google 검색이나 자체 내부 사이트 검색으로는 찾을 수 없습니다. 이제 모두 conflicting/orphaned 문서들은 삭제됩니다.
• fix a bug of legacy http:// URL references
  • http:에 대한 URL은 레거시입니다. https:로 대체되어야 합니다.
• All mentions of wiki.developer.mozilla.org should be removed
  
  • https://wiki.developer.mozilla.org/ URL 주소를 절대 경로로 변경
• [FEAT] add Issue template
  • 이제 translated-content에도 issue template이 존재합니다.
• Discuss extending transferring abilities to other ("core"?) contributors
  
  • translated-content 저장소에 대한 issue들이 content 저장소에 제기될 때, 해당 이슈를 translated-content로 옮길 수 있는 권한이 yari-core-dev team 에게만 있어서 불편함 해소를 위해 제안된 이슈입니다.  @sideshowbarker 과 @teoli2003 두 분에게 권한이 부여됐으니 해당 문제 발생 시 두 분을 멘션 해주면 됩니다.
• Remove HTML tags from code blocks (JS Operator references)
  
  • MDN 문서 내의 Operator: a + b 로 표기되던 Syntax 예시의 의미를 명확하게 Operator:를 없앤  a + b 로 표현할 것을 제안하는 PR입니다.
• Remove hidden/noinclude from JS docs
  
  • hidden과 noinclude를 가지고 있는  class는 더 이상 지원되지 않습니다. 삭제되어야 합니다.
  • Remove hidden divs from JavaScript docs
  • Unhide code blocks in live sample for Promise
• Suggestion: Remove a title in the []() syntax in markdown. (h2m converter)
  • <a> tag와 markdown 문법 []()에서 title은 이제 삭제되어야 합니다. 세부 사항은 링크 참고.

 

한국 locale 이슈

• Learn/Javascript 번역 최신화 하기' 해당 PR 마무리
  • 관련한 Draft PR들이 닫히거나 병합되면 해당 이슈를 닫을 예정입니다.
• [ko] Usage of italics in Korean
  • 한국 문서에서 <em> 기울어진 효과를 갖는 이탈릭체에 대한 제안 이슈입니다.

 

기타 이슈

• Converting MDN to Markdown
  • 7월의 가장 큰 주제인 Markdown에 대한 Discussion입니다.
• Add Persian (Dari) language to active locales
  • Persian (Dari) locale의 활성 요청을 했지만, 앞서 블로그에서도 언급했듯이 4월 이후 더 이상 다른 locale에 대해 활성 요청을 받지 않겠다는 입장에 따라 받아들여지지 않은 Discussion 내용입니다.

 

마치며

MDN 문서에 기여하고 계신 모든 분들 모두 존경합니다. 저도 역시 모두의 노력이 조금 더 잘 반영될 수 있도록 다음 한 달도 보내겠습니다.

 

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

 

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

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