쿠버네티스 문서 한글화 가이드

쿠버네티스 문서 한글화를 위한 가이드

팀 마일스톤 관리

쿠버네티스 문서 한글화팀은 커뮤니티의 현지화 가이드에 따라 한글화를 위한 팀 마일스톤과 개발 브랜치를 관리한다. 본 섹션은 한글화팀의 팀 마일스톤 관리에 특화된 내용을 다룬다.

한글화팀은 master 브랜치에서 분기한 개발 브랜치를 사용한다. 개발 브랜치 이름은 다음과 같은 구조를 갖는다.

dev-<소스 버전>-ko.<팀 마일스톤>

개발 브랜치는 약 2주에서 3주 사이의 팀 마일스톤 기간 동안 공동의 작업을 위해 사용되며, 팀 마일스톤이 종료될 때 원 브랜치로 병합(merge)된다.

업스트림(upstream)의 릴리스 주기(약 3개월)에 따라 다음 버전으로 마일스톤을 변경하는 시점에는 일시적으로 release-<소스 버전> 브랜치를 원 브랜치로 사용하는 개발 브랜치를 추가로 운영한다.

한글화팀의 정기 화상 회의 일정과 팀 마일스톤 주기는 대체로 일치하며, 정기 회의를 통해 팀 마일스톤마다 PR 랭글러(wrangler)를 지정한다.

한글화팀의 PR 랭글러가 갖는 의무는 업스트림의 PR 랭글러가 갖는 의무와 유사하다. 단, 업스트림의 PR 랭글러와는 달리 승인자가 아니어도 팀 마일스톤의 PR 랭글러가 될 수 있다. 그래서, 보다 상위 권한이 필요한 업무가 발생한 경우, PR 랭글러는 해당 권한을 가진 한글화팀 멤버에게 처리를 요청한다.

업스트림의 PR 랭글러에게 유용한 GitHub 쿼리를 기반으로 작성한, 한글화팀의 PR 랭글러에게 유용한 쿼리를 아래에 나열한다.

• CLA 서명 없음, 병합할 수 없음
• LGTM 필요
• LGTM 보유, 문서 승인 필요
• 퀵윈(Quick Wins)

팀 마일스톤 일정과 PR 랭글러는 커뮤니티 슬랙 내 #kubernetes-docs-ko 채널에 공지된다.

문체 가이드

높임말

평어체 사용을 원칙으로 하나, 일부 페이지(예: https://kubernetes.io/ko)에 한해 예외적으로 높임말을 사용한다.

명령형

어떤 일을 하도록 청자에게 요구하는 명령형 표현은 간결하고 부드러운 표현으로 정확한 의미를 전달하기 위해 어떤 일을 함께 하기를 요청하는 청유형 또는 객관적으로 진술하는 평어체로 번역한다.

번역체 지양

우리글로서 자연스럽고 무리가 없도록 번역한다.

문서 코딩 가이드

가로폭은 원문을 따름

유지보수의 편의를 위해서 원문의 가로폭을 따른다.

즉, 원문이 한 문단을 줄바꿈하지 않고 한 행에 길게 기술했다면 한글화 시에도 한 행에 길게 기술하고, 원문이 한 문단을 줄바꿈해서 여러 행으로 기술한 경우에는 한글화 시에도 가로폭을 원문과 비슷하게 유지한다.

리뷰어 삭제

때때로 원문의 코드 상단에 리뷰어가 명시되어 있는 경우가 있다. 일반적으로 원문 페이지의 리뷰어가 한글화 된 페이지를 리뷰하기 어려우므로 리소스 메타데이터에서 리뷰어 관련 코드를 삭제한다.

아래는 리뷰어 관련 코드를 삭제하는 예시를 보여준다.

- reviews:
- - reviewer1
- - reviewer
- title: Kubernetes Components
+
+
+
+ title: 쿠버네티스 컴포넌트
content_type: concept
weight: 10

용어 한글화 가이드

용어 한글화의 일반적 방침

영문 용어를 한글화할 때는 다음의 우선 순위를 따르나, 자연스럽지 않은 용어를 무리하게 선택하지는 않는다.

• 한글 단어
  • 순 우리말 단어
  • 한자어 (예: 운영 체제), 외래어 (예: 쿠버네티스, 파드)
• 한영 병기 (예: 훅(hook))
• 영어 단어 (예: Kubelet)

단, 자연스러움을 판단하는 기준은 주관적이므로 한글화 용어집을 준용하고 기존에 번역된 문서를 참고한다.

참고: 한영 병기는 페이지 내에서 해당 용어가 처음 사용될 때, 1회 적용하고 이후에는 한글만 표기한다. 그러나 필요(예: 자연스러움, 명확성 향상 등)에 따라 추가적인 한영 병기를 허용한다. 한영 병기의 대상에는 제목도 포함된다.

API 오브젝트 용어 한글화 방침

일반적으로 kubectl api-resources 결과의 kind 에 해당하는 API 오브젝트는 국립국어원 외래어 표기법에 따라 한글로 표기하고 영문을 병기한다. 예를 들면 다음과 같다.

kind 에 속하는 API 오브젝트 중에서도 일부는 표현의 간결함을 위해 한영병기를 하지 않는 등의 예외가 있으며, 예외에 대해서는 한글화 용어집에 등록된 방식을 준용한다. 예를 들면 다음과 같다.

kind 에 속하지 않는 API 오브젝트는, 한글화 용어집에 등록된 용어인 경우를 제외하고, 모두 원문 그대로 표기한다. 예를 들면 다음과 같다.

참고: 단, API 오브젝트 한글화 원칙에 예외가 있을 수 있으며, 이 경우에는 가능한 한글화 용어집을 준용한다. (예를 들면, Horizontal Pod Autoscaler 는 API 오브젝트에 대해 외래어 표기법을 적용하지 않고 원문 그대로 표기한다.)

참고: 원문에서는 API 오브젝트를 camelCase(예: configMap)로 표기하는 것을 가이드하고 있다. 그러나 한글에는 대소문자 구분이 없으므로 이를 띄어쓰기 없이 붙여서 처리한다. (예: configMap -> 컨피그맵, config Map -> 컨피그맵)

참고: API 오브젝트의 필드 이름, 파일 이름, 경로와 같은 내용은 독자가 구성 파일이나 커맨드라인에서 그대로 사용할 가능성이 높으므로 한글로 옮기지 않고 원문을 유지한다. 단, 주석에 포함된 내용은 한글로 옮길 수 있다.

기능 게이트(feature gate) 한글화 방침

쿠버네티스의 기능 게이트를 의미하는 용어는 한글화하지 않고 원문 형태를 유지한다.

기능 게이트의 예시는 다음과 같다.

• Accelerators
• AdvancedAuditing
• AffinityInAnnotations
• AllowExtTrafficLocalEndpoints
• ...

전체 기능 게이트 목록은 여기를 참고한다.

참고: 단, 해당 원칙에는 예외가 있을 수 있으며, 이 경우에는 가능한 한글화 용어집을 준용한다.

참고: 기능 게이트는 쿠버네티스 버전에 따라 변경될 수 있으므로, 쿠버네티스 및 쿠버네티스 문서의 버전에 맞는 기능 게이트 목록을 적용하여 한글화를 진행한다.

한글화 용어집 정보

쿠버네티스 한글화 용어집은 한글화된 쿠버네티스 문서의 일관성을 위해서 각 영문 용어에 대한 한글화 방법을 제시한다. 한글화 용어집에 포함된 용어는 쿠버네티스 문서 한글화팀 회의를 통해 결정되었으며, 본 문서에 대한 ISSUE 및 PR을 통해서 개선한다.

한글화 용어집 개선 가이드

한글화 용어집의 개선(추가, 수정, 삭제 등)을 위한 과정은 다음과 같다.

1. 컨트리뷰터가 개선이 필요한 용어을 파악하면, ISSUE를 생성하여 개선 필요성을 공유하거나 master 브랜치에 PR을 생성하여 개선된 용어를 제안한다.

2. 개선 제안에 대한 논의는 ISSUE 및 PR을 통해서 이루어지며, 한글화팀 회의를 통해 확정한다.

3. 리뷰어 및 승인자는 작업 중인 한글화 작업 브랜치(예: dev-1.17-ko.3)에 영향을 최소화 하기 위해서, 신규 한글화 작업 브랜치(예: dev-1.17-ko.4) 생성 시점에 맞춰 확정된 PR을 승인한다. 개선된 한글화 용어집은 신규 한글화 작업 브랜치부터 적용한다.

4. 개선된 한글화 용어집에 따라 기존의 한글 문서에 대한 업데이트가 필요하며, 컨트리뷰션을 통해서 업데이트를 진행한다.

한글화 용어집