쿠버네티스 한글화 모범 사례

이 문서는 쿠버네티스 문서 한글화 과정에서 자주 반복되는 수정 리뷰 사례와 그에 대한 권장 표현 예시를 모범 사례로 정리한 문서이다. 여러 기여자와 리뷰어의 경험을 바탕으로 작성되었으며, 특히 새로운 기여자들이 쉽게 참고할 수 있도록 구성하였다.

다양한 사례를 체계적으로 살펴볼 수 있도록 다음과 같이 카테고리로 분류한다. 정렬은 가나다순이다.

구분설명
기여 방식리뷰 절차, 협업 방식, 규칙 등 기여 과정 전반에 관한 사항
문체 및 표현번역된 문장의 자연스러움, 어투, 문장 구조 등과 관련된 사항
원문영어 원문에 대한 번역 방식이나 표기 관련 사항
용어단어·고유명사 등에 대한 번역 방식이나 표기 관련 사항

모범 사례 문서 기여 지침

본 문서는 누구든지 참고하고, PR을 통해 추가 및 개선할 수 있다.

  • 신규 사례를 작성할 때는 다음의 작성 템플릿을 준수한다.
  • 추가 사례는 반드시 한글화 팀 논의나 리뷰어 검토 등 명확한 합의 근거를 확인한 후 등록한다.
  • 추가 사례의 경우, 이전 사례와 구분하기 위해 구분선(---)을 추가한 뒤 작성한다.
  • 사례에는 원문의 불필요한 부분은 제거하고 꼭 필요한 내용만 간결히 기록한다.
  • 사례 설명에서 강조가 필요한 부분은 마크다운(Markdown) 서식을 활용한다.

작성 템플릿

### (제목은 명사 또는 명사형 종결 어미로 작성)

(간결하게 내용 작성)

#### 예시
* 해당하는 경우에만 작성

**[영어 원문]**
> (내용 작성)

**[권장 번역]**
> (내용 작성)

#### 참고 링크
* 해당하는 경우에만 작성
- (링크)

모범 사례

기여 방식

리뷰 반영 과정에서는 추가 커밋을 작성하여 변경 사항을 쉽게 확인할 수 있도록 함

  • 기여자가 리뷰 반영 과정에서 amend/squash 후 force-push 를 하게 되면, 기존 리뷰 코멘트가 파일 뷰 라인에 유지되지 않는 문제가 발생한다.
  • 그 결과, 리뷰어가 코멘트 위치를 다시 찾아가며 확인해야 하는 어려움이 있다.
  • 따라서, 리뷰 과정에서는 커밋을 누적하여 변경 의도를 명확히 드러내고, 최종 승인 직전에 하나의 커밋으로 합치는 것이 바람직하다.
  • 단, 이는 리뷰어와 기여자 간의 합의에 따라 조정할 수 있는 원칙이며, 상황에 따라 예외가 존재할 수 있다.

참고 링크

Github Profile Name은 가급적 영문으로 작성함

  • kubernetes/website 저장소는 한국어뿐만 아니라 여러 언어가 함께 사용되는 저장소이기 때문이다.

이슈, 풀 리퀘스트, 커밋 메시지는 영문으로 작성함

  • 이슈와 풀 리퀘스트 제목은 반드시 영문으로 작성하며, 본문 역시 가급적 영문으로 작성한다.
  • 커밋 메시지는 영문으로 작성하고, 기존 저장소에서 사용 중인 커밋 메시지 스타일을 준수한다.
  • kubernetes/website 저장소는 한국어뿐만 아니라 여러 언어가 함께 사용되는 저장소이기 때문이다.
  • 이슈나 풀 리퀘스트의 내부 코멘트는 한국어 사용이 가능하다.

문체 및 표현

한국어 문장 부호 체계에 맞게 변환하여 사용함

  • 영어 원문에서 사용된 문장 부호는 한국어 문장에서 동일한 기능을 수행하지 못하는 경우가 있으므로, 번역 시에는 한국어 문장 부호 체계에 맞게 조정하는 것을 원칙으로 한다.
  • 예를 들어, 콜론(:)은 마침표(.)로 바꾸는 식으로 자연스럽게 변환한다.

예시

[영어 원문]

At the moment, the VPA can operate in four different modes:

[권장 번역]

현재, VPA는 다음 네 가지 모드로 작동된다.

참고 링크

앵커 링크 현지화 가이드라인

  • 앵커 링크는 정확한 이름으로 지정한다.
  • 헤더에 별도의 앵커가 없는 경우, Minimum required content → minimum-required-content와 같은 패턴으로 자동 할당된다.
  • 한글로 헤더가 변경되었다면, 영문 앵커 링크도 한글로 변경한다.
    • ex. (#minimum-required-content) → (#최소-요구-콘텐츠)
  • GitHub에 현지화 팀 추가하기 {#Add-your-localization-team-in-GitHub}와 같이 기존 원문에 이미 특별히 영문 앵커가 지정되어 있는 경우가 있다.
    • 이 경우, 해당 앵커는 한글 문서에서도 그대로 영문으로 준용한다.
  • 변경 후에 실제 링크가 동작하는지 반드시 확인해야 한다.

예시

[영어 원문]

you must localize all the [minimum required content](#minimum-required-content)

[권장 번역]

[최소 요구 콘텐츠](#최소-요구-콘텐츠)를 모두 현지화해야 한다.

참고 링크

블로그 게시글 번역 시 격식체를 사용할 수 있음

  • 블로그 게시글의 번역은 기술 문서와 달리 블로그 게시글의 성격에 따라서, 격식체(‘~습니다/합니다’체)를 선택적으로 사용할 수 있다.

참고 링크

번역체를 지양함

  • 쿠버네티스의 컴포넌트와 같이 문서에서 격조사 ~의가 과도하게 사용되지 않도록 불필요한 격조사는 생략하는 것이 좋다.

예시

[영어 원문]

title: Kubernetes Components

[권장 번역]

title: 쿠버네티스 컴포넌트

참고 링크

원문

가급적 원문을 준수함

  • 한글화 가이드에서는 가급적 원문을 준수하면서 자연스럽게 번역하는 것을 원칙으로 한다.
  • 심지어 영어 원문에 오류가 있다 하더라도 임의로 수정하지 않고 원문을 따른다. (영어 원문의 오류를 수정한 후, 한글 문서에도 반영한다. SIG Docs Localization Subproject는 현지화 팀의 영어 원문 수정 기여도 매우 권장한다.)
  • 원문에 없는 내용이나 양식을 한글 문서에 임의로 추가하지 않는다.

예시

[영어 원문]

If you want to use minikube again to learn more about Kubernetes, you don't need to delete it.

[권장 번역]

쿠버네티스를 더 배우기 위해 minikube를 다시 사용할 계획이라면, 굳이 삭제하지 않아도 된다.

참고 링크

영어 원문과 유사한 위치에서 개행하여 전체 라인 수를 동일하게 유지함

  • 이 규칙은 한글화된 문서의 유지보수성과 리뷰 효율을 높이기 위해 한글화 팀에서 운영하는 원칙이다.
  • 영어 원문과 한국어 번역의 구조를 쉽게 비교할 수 있도록 문장 개행 위치를 원문과 가능한 한 유사하게 맞춘다.
  • 영어와 한국어의 문장 구조 차이로 인해 개행 지점이 애매한 경우에도, 독자의 이해를 해치지 않는 범위에서 최대한 원문 개행 위치를 고려하여 번역문을 개행한다.
  • 이러한 방식으로 작성하면, 영문 원문과 번역문의 총 라인 수가 일치하여 유지보수 및 리뷰 과정에서 차이를 빠르게 식별할 수 있다.

예시

[영어 원문]

Create a namespace so that the resources you create in this exercise are

isolated from the rest of your cluster.

[권장 번역]

이 실습에서 생성하는 리소스가 클러스터의 다른 리소스와

격리되도록 네임스페이스를 생성한다.

참고 링크

용어

한글화 용어집에 등록되지 않은 용어

  • 쿠버네티스 한글화 팀은 한글화 용어집을 준용하며, 등록되지 않은 용어의 경우 논의를 통해 용어집에 등록할 수 있다.
  • 자세한 내용은 쿠버네티스 한글화 가이드를 참고한다.

참고 링크

영문 병기는 기본적으로 문서에서 해당 용어가 처음 등장할 때 한 번만 표기함

  • 단, 여러 번 표기가 필요한 경우 리뷰어와 기여자가 조율하여 결정할 수 있다.

예시

[영어 원문]

Create a ResourceQuota

Here is the configuration file for a ResourceQuota object:

[권장 번역]

리소스쿼터(ResourceQuota) 생성

다음은 리소스쿼터 오브젝트에 대한 설정 파일이다.

참고 링크

쿠버네티스 오브젝트 또는 필드 명칭 번역

예시

[영어 원문]

to enforce ... and set resources such as cpu/memory requests and limits.

[권장 번역]

... cpu 혹은 메모리와 같은 자원의 요청(request)과 상한(limit)을 설정하기 위함이다.

참고 링크

한 페이지 내 동일 단어는 일관성 있게 번역함

  • 백틱(``)으로 표기된 필드명이나 고유 영단어를 그대로 사용해야 하는 경우를 제외하고, 동일한 단어는 한 페이지 내에서 일관되게 번역한다.
    • 예를 들어, hostname, subdomain 등이 있다.
  • 영어 원문에서 오브젝트명과 일반 용어가 동일한 단어로 혼용되어 있는 경우, 리뷰어와 기여자가 논의를 통해 표기를 결정할 수 있다.
    • 예를 들어, ServiceAccount(API 오브젝트명), Service Account(일반 용어)가 있다.

참고 링크

최종 수정 October 01, 2025 at 12:08 AM PST: Add Kubernetes Korean Localization Best Practices (0e4e869940)