오픈소스 입문자를 위한 Kubernetes 지역화: 누락된 문서 탐지 스크립트 구현

쿠버네티스 문서 생태계의 지역화(localization)

한번쯤은 모두들 들어가봤을 공식 문서다. https://kubernetes.io/ko/

 

 

kubernetes-sigs/docs

쿠버가 오픈소스인만큼 문서도 사용자들의 자유로운 참여로 추가, 수정되고 있다.

 

이 문서의 저장소인 kubernetes-sigs/docs는 kubernetes.io에 배포되는 모든 문서나 번역본을 모두 포함하고 있다.

 

지역화(localization)는 영문 문서를 진실의 원천(Source of Truth)로 두고 관리하는 SIG-DOCS팀의 산하 서브 프로젝트이다.

이 공식 문서 생태계를 지역별로 번역·관리하는 활동으로, 영문 문서를  두고 다국어 번역, 동기화하는 downstream 작업이다.

 

쿠버네티스 지역화를 입문자에게 추천하는 이유

오픈소스 입문으로 굉장히 매력적이라 생각한다. 이거만한게 없다.

 

 

1. 번역 작업을 통해서 공식 문서를 학습할 기회도 마련되고 CNCF Graduated인 만큼 성숙한 생태계를 경험할 수 있다.

수능 만점자의 '교과서 위주로 공부했어요'를 당신도 공식 문서와 함께 할 수 있다.

 

2. 한국어로 리뷰하거나 Slack에서 소통할 수 있기 때문에 편리하다.

그리고 무엇보다도 송구스러울 정도로 친절하게 하나하나 가르쳐주신다...

 

3. 특히 입문자들에게 막연히 어렵고 힘든, 미지의 영역으로 보이는 오픈소스 기여라는 영역을 접근하기 쉽게 해준다.

가장 큰 장점. 첫 시작이 어려운 거지 이만큼 성숙한 체계 아래에서 기여 프로세스를 익힌다면 다른 오픈소스에서도 그 자신감을 여실히 뽐낼 수 있다.

 

 

오픈소스에 첫 입문하기

1. 시작하기에 앞서, CLA 인증 설정하기

쿠버네티스 기여를 시작하기 전에 반드시 CNCF CLA(Contributor License Agreement) 서명이 필요하다.

 

서명하고 인증해야하는데 안하고 PR 올리면 댓글로 봇이 잔뜩 화내는데..

빨간색이 강렬해서 죄지은거 같고 식은 땀이 줄줄 흐른다.

 

해버리자.

https://github.com/kubernetes/community/blob/master/CLA.md

community/CLA.md at master · kubernetes/community

 

쿠버는 아니지만, DCO 설정같은 것도 다른 오픈소스에서 요구하는 경우가 많으니 미리 해두면 좋다.

 

2. 작업할 문서를 찾자 (+ 쉘스크립트 구현)

일단 영문(en)과 한글(ko) 문서를 비교하며 작업거리를 찾는다.

• content/en/*, content/ko/*

 

난 그냥 스크립트 짰다...

영문에 존재하지만 한국어로 된 문서가 없는 목록을 나열하도록 해서 간단하게 확인할 수 있다.

 

 

find-works.sh

find content/en -name "*.md" | sed 's|content/en/||' | sort > /tmp/en.txt  
find content/ko -name "*.md" | sed 's|content/ko/||' | sort > /tmp/ko.txt  

echo "최소 요구 사항(상위 50개):"  
comm -23 /tmp/en.txt /tmp/ko.txt | grep -E "^(docs/home/|docs/setup/|docs/tutorials/|releases/|docs/concepts/)" | head -50  

echo "전체 문서 (상위 10개):" && comm -23 /tmp/en.txt /tmp/ko.txt | head -10  
rm /tmp/en.txt /tmp/ko.txt

 

 

결과적으로 아래와 같은 형식으로 작업할 리스트를 확인할 수 있다!

./find-works.sh

docs/concepts/cluster-administration/compatibility-version.md
docs/concepts/cluster-administration/coordinated-leader-election.md
docs/concepts/cluster-administration/kube-state-metrics.md
...

 

3. 이슈 할당

먼저 이미 해당 작업을 진행중인 사람이 있는지 이슈란에서 검색해보는게 필수적이다.

 

Assign을 통해 일감을 누가 맡을지 지정해야 각기다른 기여자들간 충돌이 발생하지 않는다. 

 

라벨링을 한국어로 설정해서 검색하면 찾기 편하다!

대충 입력해본건데 저 문서는 아직 번역안된거라 누구나 참여해도 된다.

 

이슈가 존재하지 않는다면 직접 작성해서 공식적으로 해당 문서를 할당받아야 한다. 이건 이제 내꺼니까 아무도 건들지마라

 

k8s-ci-robot 이 친구 앞으로 자주 보게 될 친구인데 주로 테스트나 라벨링하는데 쓰인다.

보이는 것처럼 이슈에 코멘트 형식으로 명령어를 달면 해당 문서 작업 이슈에 자신을 할당할 수 있다. 

 

이슈는 템플릿이 잘 나와있어서 그대로 따라 적으면 되지만, 영문으로 적어야해서 다른 PR이나 이슈를 참고해서 적으면 된다.

 

3. 영문 문서의 번역

이정도는 알아서 하쇼

 

친절하게 설명해주시겠지만 먼저 숙지하고 이쁨받도록

• 쿠버네티스 한글화 가이드: https://kubernetes.io/ko/docs/contribute/localization_ko/
• 쿠버네티스 한글화의 모범 사례: https://kubernetes.io/ko/docs/contribute/localization_ko_best_practice/

 

4. PR 제출전에 미리 고려해야할 검사 항목

번역 품질에 대한 스타일 가이드 준수, 일관성 검사 등

 

3-1. i18n 문자열 검사

cat i18n/en/en.toml
cat i18n/ko/ko.toml 

comm -23 <(grep "^\[" i18n/en/en.toml | sort) \  
         <(grep "^\[" i18n/ko/ko.toml | sort)

 

3-2. 문서 내의 하이퍼링크 검사

scripts/linkchecker.py -f content/ko/docs/tutorials/configuration/pod-sidecar-containers.md

 

3-3. PR에서 Netlify로 확인하기 or 로컬에서 테스트하기

make container-serve # http://localhost:1313

 

 

다음과 같이 확인할 수 있다.