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

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

팀 마일스톤 관리

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

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

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

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

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

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

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

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

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

문체 가이드

높임말

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

명령형

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

명령형 문장번역체
사이트를 방문하라사이트를 방문하자 (청유형)
가이드를 참고하라가이드를 참고한다 (평어체)

번역체 지양

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

번역체자연스러운 문장
-되어지다 (이중 피동 표현)-되다
짧은 다리를 가진 돼지다리가 짧은 돼지
그는 그의 손으로 숟가락을 들어 그의 밥을 먹었다그는 손으로 숟가락을 들어 밥을 먹었다
접시를 씻고설거지를 하고
가게에 배들, 사과들, 복숭아들이 있다 (과다한 복수형)가게에 배, 사과, 복숭아들이 있다

문서 코딩 가이드

가로폭은 원문을 따름

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

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

리뷰어 주석 처리

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

아래는 리뷰어 관련 코드를 주석 처리하는 예시를 보여준다.

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

용어 한글화 가이드

용어 한글화의 일반적 방침

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

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

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

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

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

API 오브젝트(kind)한글화(외래어 표기 및 영문 병기)
ClusterRoleBinding클러스터롤바인딩(ClusterRoleBinding)
ConfigMap컨피그맵(ConfigMap)
Deployment디플로이먼트(Deployment)
PersistentVolumeClaim퍼시스턴트볼륨클레임(PersistentVolumeClaim)
......

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

API 오브젝트(kind)한글화(외래어 표기)
Pod파드
Service서비스
......

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

API 오브젝트(kind가 아닌 경우)한글화(원문 유지)
ClusterRoleBindingListClusterRoleBindingList
ClusterRoleListClusterRoleList
ConfigMapEnvSourceConfigMapEnvSource
ConfigMapKeySelectorConfigMapKeySelector
PersistentVolumeClaimListPersistentVolumeClaimList
PersistentVolumeClaimSpecPersistentVolumeClaimSpec
......

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

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

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

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

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

한글화 용어집 정보

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

한글화 용어집 개선 가이드

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

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

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

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

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

한글화 용어집

English한글비고
Access접근
ActiveActive잡의 상태
Active Job액티브 잡
Addons애드온
admission controller어드미션 컨트롤러
Age기간
Allocation할당량
alphanumeric영숫자
Annotation어노테이션
APIServiceAPI서비스(APIService)API 오브젝트인 경우
App
Appendix부록
Application애플리케이션
ArgsArgs약어의 형태이므로 한글화하지 않고 영문 표기
array배열
autoscaler오토스케일러
availability zone가용성 영역(availability zone)
bare pod베어(bare) 파드
beta베타
Binding바인딩(Binding)API 오브젝트인 경우
boilerplate상용구
Boot부트
Bootstrap부트스트랩
Build빌드
Cache캐시
Calico캘리코(Calico)
canary카나리(canary)릴리스 방식에 관련한 용어인 경우에 한함
cascading캐스케이딩(cascading)
CertificateSigningRequestCertificateSigningRequestAPI 오브젝트인 경우
character set캐릭터 셋
Charts차트
checkpoint체크포인트
Cilium실리움(Cilium)
CLICLI
Cluster클러스터
ClusterRole클러스터롤(ClusterRole)API 오브젝트인 경우
ClusterRoleBinding클러스터롤바인딩(ClusterRoleBinding)API 오브젝트인 경우
Command Line Tool커맨드라인 툴
ComponentStatus컴포넌트스테이터스(ComponentStatus)API 오브젝트인 경우
ConfigMap컨피그맵(ConfigMap)API 오브젝트인 경우
configuration구성, 설정
Connection연결
containerized컨테이너화 된
Context컨텍스트
Control Plane컨트롤 플레인
controller컨트롤러
ControllerRevision컨트롤러리비전(ControllerRevision)API 오브젝트인 경우
cron job크론 잡
CronJob크론잡(CronJob)API 오브젝트인 경우
CSIDriverCSI드라이버(CSIDriver)API 오브젝트인 경우
CSINodeCSI노드(CSINode)API 오브젝트인 경우
custom metrics사용자 정의 메트릭
custom resource사용자 정의 리소스
CustomResourceDefinition커스텀리소스데피니션(CustomResourceDefinition)API 오브젝트인 경우
Daemon데몬
DaemonSet데몬셋(DaemonSet)API 오브젝트인 경우
Dashboard대시보드
Data Plane데이터 플레인
Deployment디플로이먼트(Deployment)API 오브젝트인 경우
deprecated사용 중단(deprecated)
descriptor디스크립터, 식별자
Desired number of pods의도한 파드의 수
Desired State의도한 상태
disruption중단(disruption)
distros배포판
Docker도커
DockerfileDockerfile
Docker SwarmDocker Swarm
Downward API다운워드(Downward) API
draining드레이닝(draining)
egress이그레스, 송신(egress)
endpoint엔드포인트
EndpointSlice엔드포인트슬라이스(EndpointSlice)API 오브젝트인 경우
Endpoints엔드포인트(Endpoints)API 오브젝트인 경우
entry point진입점
Event이벤트(Event)API 오브젝트인 경우
evict축출하다
eviction축출
ExecExec
expose노출시키다
extension익스텐션(extension)
FailedFailed파드의 상태에 한함
Federation페더레이션
field필드
finalizer파이널라이저(finalizer)
Flannel플란넬(Flannel)
form형식
Google Compute EngineGoogle Compute Engine
hash해시
headless헤드리스
health check헬스 체크
Heapster힙스터(Heapster)
Heartbeat하트비트
HomebrewHomebrew
hook훅(hook)
Horizontal Pod AutoscalerHorizontal Pod Autoscaler예외적으로 API 오브젝트에 대해 외래어 표기법 적용하지 않고 원문 그대로 표기
hosted zone호스팅 영역
hostname호스트네임
Huge pageHuge page
Hypervisor하이퍼바이저
idempotent멱등성
Image이미지
Image Pull Secrets이미지 풀(Pull) 시크릿
Ingress인그레스(Ingress)API 오브젝트인 경우
IngressClass인그레스클래스(IngressClass)API 오브젝트인 경우
Init Container초기화 컨테이너
Instance group인스턴스 그룹
introspection인트로스펙션(introspection)
Istio이스티오(Istio)
Job잡(Job)API 오브젝트인 경우
kube-proxykube-proxy
KubeletKubelet
Kubernetes쿠버네티스
Kube-routerKube-router
label레이블
Lease리스(Lease)API 오브젝트인 경우
lifecycle라이프사이클
LimitRange리밋레인지(LimitRange)API 오브젝트인 경우
limit한도(limit)리소스의 개수나 용량을 한정하기 위한 수치로 사용된 경우 선택적으로 사용 (API 오브젝트의 속성으로 limit을 사용한 경우는 가능한 영문 유지)
Linux리눅스
load부하
LocalSubjectAccessReview로컬서브젝트액세스리뷰(LocalSubjectAccessReview)API 오브젝트인 경우
Log로그
loopback루프백(loopback)
LostLost클레임의 상태에 한함
Machine머신
manifest매니페스트
Master마스터
metadata메타데이터
metric메트릭
masquerading마스커레이딩
MinikubeMinikube
Mirror pod미러 파드(mirror pod)
monitoring모니터링
multihomed멀티홈드(multihomed)
MutatingWebhookConfigurationMutatingWebhookConfigurationAPI 오브젝트인 경우
naked pod네이키드(naked) 파드
Namespace네임스페이스(Namespace)API 오브젝트인 경우
netfilter넷필터(netfilter)
NetworkPolicy네트워크폴리시(NetworkPolicy)API 오브젝트인 경우
Node노드(Node)API 오브젝트인 경우
node lease노드 리스(lease)
Object오브젝트
observability가시성(observability)
Operator오퍼레이터쿠버네티스의 소프트웨어 익스텐션을 의미하는 경우
Orchestrate오케스트레이션하다
Output출력
parameter파라미터
patch패치
payload페이로드(payload)
PendingPending파드, 클레임의 상태에 한함
PersistentVolume퍼시스턴트볼륨(PersistentVolume)API 오브젝트인 경우
PersistentVolumeClaim퍼시스턴트볼륨클레임(PersistentVolumeClaim)API 오브젝트인 경우
pipeline파이프라인
placeholder pod플레이스홀더(placeholder) 파드
Pod파드API 오브젝트인 경우에도 표현의 간결함을 위해 한영병기를 하지 않음
Pod Preset파드 프리셋
PodAntiAffinity파드안티어피니티(PodAntiAffinity)
PodDisruptionBudgetPodDisruptionBudgetAPI 오브젝트인 경우
PodSecurityPolicy파드시큐리티폴리시(PodSecurityPolicy)API 오브젝트인 경우
PodTemplate파드템플릿(PodTemplate)API 오브젝트인 경우
postfix접미사
prefix접두사
PriorityClass프라이어리티클래스(PriorityClass)API 오브젝트인 경우
Privileged특권을 가진(privileged)
Prometheus프로메테우스
proof of concept개념 증명
Pull Request풀 리퀘스트
Pull Secret Credentials풀(Pull) 시크릿 자격증명
QoS ClassQoS 클래스
Quota쿼터
readiness gate준비성 게이트(readiness gate)
readiness probe준비성 프로브(readiness probe)
ReadyReady
Reclaim Policy반환 정책
redirect리다이렉트(redirect)
redirection리다이렉션
Registry레지스트리
Release릴리스
ReplicaSet레플리카셋(ReplicaSet)API 오브젝트인 경우
replicas레플리카
ReplicationController레플리케이션컨트롤러(ReplicationController)API 오브젝트인 경우
repository리포지터리
request요청(request)리소스의 개수나 용량에 대한 요청 수치를 표현하기 위해 사용된 경우 선택적으로 사용 (API 오브젝트 속성으로 request를 사용한 경우는 가능한 영문을 유지)
resource리소스
ResourceQuota리소스쿼터(ResourceQuota)API 오브젝트인 경우
return반환하다
revision리비전
Role롤(Role)API 오브젝트인 경우
RoleBinding롤바인딩(RoleBinding)API 오브젝트인 경우
rollback롤백
rolling update롤링 업데이트
rollout롤아웃
Romana로마나(Romana)
RunningRunning파드의 상태에 한함
runtime런타임
RuntimeClass런타임클래스(RuntimeClass)API 오브젝트인 경우
Scale스케일
Secret시크릿(Secret)API 오브젝트인 경우
segment세그먼트
Selector셀렉터
Self-healing자가 치유
SelfSubjectAccessReview셀프서브젝트액세스리뷰(SelfSubjectAccessReview)API 오브젝트인 경우
SelfSubjectRulesReviewSelfSubjectRulesReviewAPI 오브젝트이지만 용어를 구성하는 단어 중 복수형 Rules를 '룰스'로 외래어 표기하는 경우 한국어 독자에게 다소 생경할 수 있어 예외적으로 영문 용어를 사용함
Service서비스API 오브젝트인 경우에도 표현의 간결함을 위해 한영병기를 하지 않음
ServiceAccount서비스어카운트(ServiceAccount)API 오브젝트인 경우
service discovery서비스 디스커버리
service mesh서비스 메시
Session세션
Session Affinity세션 어피니티(Affinity)
Setting세팅
Shell
sidecar사이드카(sidecar)
Sign In로그인
Sign Out로그아웃
skew차이(skew)
snippet스니펫(snippet)
spec명세, 스펙, 사양
specification명세
StatefulSet스테이트풀셋(StatefulSet)API 오브젝트인 경우
stateless스테이트리스
Static pod스태틱(static) 파드
StorageClass스토리지클래스(StorageClass)API 오브젝트인 경우
SubjectAccessReview서브젝트액세스리뷰(SubjectAccessReview)API 오브젝트인 경우
Sub-Object서브-오브젝트
support지원
Surge증가율롤링업데이트 전략에 한함
System시스템
taint테인트(taint)
Task태스크
telepresence텔레프레즌스(telepresence)
TerminatedTerminated파드의 상태에 한함
TokenReview토큰리뷰(TokenReview)API 오브젝트인 경우
tolerations톨러레이션(toleration)
Topology spread constraints토폴로지 분배 제약 조건
Tools도구
traffic트래픽
Type타입
ubuntu우분투
use case유스케이스
userspace유저스페이스(userspace)
Utilization사용량, 사용률
ValidatingWebhookConfigurationValidatingWebhookConfigurationAPI 오브젝트인 경우
verbosity로그 상세 레벨(verbosity)
virtualization가상화
Volume볼륨
VolumeAttachment볼륨어태치먼트(VolumeAttachment)API 오브젝트인 경우
WaitingWaiting파드의 상태에 한함
Walkthrough연습
Weave-net위브넷(Weave Net)Weaveworks 사의 솔루션 공식 명칭은 'Weave Net'이므로 한영병기 시 공식 명칭 사용
Windows윈도우
Worker워커노드의 형태에 한함
Workload워크로드
YAMLYAML