PEP 545 – Python 문서 번역

Author:: Julien Palard <julien at palard.fr>, Inada Naoki <songofacandy at gmail.com>, Victor Stinner <vstinner at python.org>
Status:: Active
Type:: Process
Topic:: Governance
Created:: 04-Mar-2017
Resolution:: Python-Dev message

Table of Contents

초록
동기
근거
변경 사항
새 번역 절차
이전 논의
참고 자료
Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

초록

이 PEP의 목적은 기존 Python 문서 번역을 더 쉽게 이용하고 발견할 수 있도록 만드는 것입니다. 이를 통해 새로운 번역자와 새로운 번역을 유치하고 동기를 부여할 수 있기를 바랍니다.

번역된 문서는 python.org에서 호스팅됩니다. 활발히 활동하는 두 번역 팀의 예시는 다음과 같습니다.

https://docs.python.org/fr/: 프랑스어
https://docs.python.org/ja/: 일본어

https://docs.python.org/en/ 은 https://docs.python.org/ 으로 리디렉션됩니다.

번역된 문서의 소스는 GitHub의 Python 조직에서 호스팅됩니다: https://github.com/python/. 기여자는 Documentation Contribution Agreement에 동의해야 합니다.

동기

freenode의 프랑스어 #python-fr IRC 채널에서는 영어를 하지 못해 Python 공식 문서를 읽을 수 없는 사람들을 만나는 일이 드물지 않습니다. Python은 모든 언어로 모든 사용자가 널리 이용할 수 있기를 바랍니다. 이것이 Python 3이 ASCII가 아닌 식별자도 지원하는 이유이기도 합니다: PEP 3131

번역이 d.p.o.에 표시되지는 않지만, Python 문서를 모국어로 번역하는 사람들의 그룹이 최소 4개 있습니다(프랑스어 [16] [17] [18], 일본어 [19] [20], 스페인어 [21], 헝가리어 [26] [27]). 그 밖에도 덜 알려지고 덜 조직화된 그룹들이 문서를 번역하고 있으며, 러시아어 [25], 중국어 및 한국어 그룹에 관한 이야기를 들었습니다. 아직 발견하지 못한 다른 그룹들도 존재할 수 있습니다. 이 PEP는 개발자, 신규 사용자 및 잠재적 번역자가 쉽게 찾을 수 있도록 번역을 docs.python.org로 옮기는 방법을 설명하는 규칙을 정의합니다.

일본 팀은 2017년 3월 기준으로 문서의 약 80%를 번역했으며, 프랑스 팀은 약 20%를 번역했습니다. 프랑스어 번역은 2016년에 6%에서 23%로 증가했으며 [13] 7명의 기여자가 참여했습니다 [14]. 이는 번역 팀이 문서가 변경되는 속도보다 더 빠르게 작업할 수 있음을 보여 줍니다.

중국어 번역에 관한 Xiang Zhang의 말을 인용하면 다음과 같습니다.

저는 공식 문서의 일부를 번역하려고 하는 여러 그룹을 보았습니다. 그러나 이들의 노력은 하나의 공통된 결과를 향해 작업하도록 조직되어 있지 않고, 그 결과가 웹의 여러 곳에 보관되어 찾기 어렵기 때문에 분산되고 빠르게 사라집니다. 공식적인 번역이 있다면 이러한 어려움을 덜어 주는 데 도움이 될 수 있습니다.

근거

번역

이슈 추적기

번역에 대해 생성된 이슈는 번역 언어로 작성될 수 있으며, 이는 잡음으로 간주될 수 있을 뿐 아니라 일관성도 없으므로, 이슈를 CPython issue tracker에 등록해서는 안 됩니다.

모든 번역은 자체 GitHub 프로젝트를 가져야 하므로(Repository for PO Files 참조), 연결된 GitHub 이슈 추적기를 사용해야 합니다.

모든 경고에도 불구하고 어떤 언어로든 작성된 번역 관련 이슈가 이슈 추적기에 들어가 발생할 수 있는 잡음을 고려하면, 분류 작업을 수행해야 합니다. 번역은 이미 존재하며 실제로 이슈 추적기에서 잡음의 원인이 되지 않는다는 점을 고려하면, 감당할 수 없을 정도로 많은 작업이 발생할 것으로 예상되지는 않습니다. Xiang Zhang과 Victor Stinner이 이미 분류 작업을 수행하고 있고 Julien Palard도 이 작업을 도울 의향이 있다는 점을 고려하면, 이슈 추적기에서 잡음이 발생할 것으로 예상되지는 않습니다.

또한 언어 팀 코디네이터(Language Team를 참조하십시오)는 필요한 경우 이슈 작성자의 언어로 올바른 이슈 트래커를 적절히 표시하여 이슈 트래커 분류를 지원해야 합니다.

분기

번역 팀은 최신 안정 버전에 집중하고, 도구(스크립트, 번역 메모리, …)를 사용하여 한 분기에서 완료된 작업을 다른 분기로 자동 번역해야 합니다.

Note

번역 메모리는 이전에 번역된 단락(삭제된 단락도 포함)의 일종의 데이터베이스입니다. Sphinx Internationalization도 참조하십시오.

현재 가장 최신인 안정 분기가 번역되며, 번역을 다른 분기로 전파할 수 있습니다. 이전 분기의 문서를 빌드하는 스크립트는 번역을 지원하도록 수정해야 합니다 [12]. 반면 이러한 분기는 이제 보안 수정만 허용합니다.

개발 분기(main)는 안정 분기보다 번역 우선순위를 낮게 설정해야 합니다. 그러나 다음 릴리스에 대비하여 팀이 작업할 수 있도록 docsbuild-scripts는 어쨌든 이를 빌드해야 합니다.

호스팅

도메인 이름, 콘텐츠 협상 및 URL

다음 중 하나를 변경하여 서로 다른 번역을 식별할 수 있습니다: 국가 코드 최상위 도메인(CCTLD), 경로 세그먼트, 서브도메인 또는 콘텐츠 협상입니다.

각 번역에 CCTLD를 구매하는 것은 비용과 시간이 많이 들며, 이미 등록된 경우에는 때때로 거의 불가능하므로 이 방법은 피해야 합니다.

“es.docs.python.org” 또는 “docs.es.python.org”와 같은 서브도메인을 사용하는 것은 가능하지만 혼란스럽습니다(”es.docs.python.org 또는 docs.es.python.org 중 어느 것입니까?). pt-br.doc.python.org와 같은 서브도메인의 하이픈은 흔하지 않으며, SEOMoz [23]는 하이픈의 존재를 부정적인 요인으로 상관 분석했습니다. 서브도메인에서 밑줄을 사용하는 것은 RFC 1123의 2.1절에 따라 금지됩니다. 마지막으로, 서브도메인을 사용하면 언어마다 TLS 인증서를 생성해야 합니다. 이는 유지 관리가 더 많이 필요할 뿐 아니라, 버전 전환기와 마찬가지로 주어진 버전에 번역이 존재하는지 프리플라이트에서 확인하려는 경우 언어 전환기에도 문제를 일으킵니다. 프리플라이트는 아마도 동일 출처 정책에 의해 차단될 것입니다. 와일드카드 TLS 인증서는 매우 비쌉니다.

콘텐츠 협상(요청의 HTTP 헤더 Accept-Language 및 Vary: Accept-Language)을 사용하면 사용자가 언어를 쉽게 변경할 수 없어 사용자 경험이 나빠집니다. Mozilla에 따르면, “이 헤더는 특정 URL처럼 명시적인 사용자 결정에 의해 제어되는 다른 방법으로 서버가 언어를 확인할 수 없을 때 사용하는 힌트입니다.” [24]. 언어를 쉽게 변경할 수 있어야 하므로 콘텐츠 협상을 주요 언어 결정 방법으로 사용해서는 안 되며, 다른 방법이 필요합니다.

마지막 방법은 URL 경로를 사용하는 것입니다. URL 경로는 읽기 쉬워 보이고, 한 언어에서 다른 언어로 쉽게 전환할 수 있으며, 하이픈도 잘 수용합니다. 일반적으로 다음과 같습니다: “docs.python.org/de/” 또는 하이픈을 사용하면 “docs.python.org/pt-BR/”입니다.

버전의 경우 sphinx-doc은 여러 언어에 대한 컴파일을 지원하지 않으므로, 버전에서 이미 수행하는 방식과 정확히 같이 경로 아래를 루트로 하는 전체 빌드를 구성하게 됩니다.

따라서 “docs.python.org/de/3.6/” 또는 “docs.python.org/3.6/de/”로 지정할 수 있습니다. 여기서 다음과 같은 질문이 생깁니다: “언어가 여러 버전을 포함합니까, 아니면 버전이 여러 언어를 포함합니까?” 버전은 어떤 경우든 존재하고 특정 버전에 대한 번역은 존재할 수도 존재하지 않을 수도 있으므로 “docs.python.org/3.6/de/”를 선호할 수 있지만, 그렇게 하면 언어가 곳곳에 흩어집니다. “/de/3.6/”으로 지정하는 편이 더 명확하며, 이는 “/de/” 아래의 모든 내용이 독일어로 작성된다는 의미입니다. 버전을 끝에 두는 것은 문서 독자들이 가진 습관이기도 합니다. 독자들은 경로의 끝을 변경하여 버전을 쉽게 바꾸기를 원합니다.

따라서 다음 패턴을 사용해야 합니다: “docs.python.org/LANGUAGE_TAG/VERSION/”.

현재 문서는 “/en/”으로 이동하지 않고, 대신 “docs.python.org/en/”이 “docs.python.org”로 리디렉션됩니다.

언어 태그

언어 태그의 일반적인 표기법은 ISO 639를 기반으로 하는 IETF Language Tag입니다 [4]. 단, gettext는 태그를 연결할 때 대시(예: pt-BR) 대신 밑줄(예: pt_BR)을 사용하는 ISO 639 태그를 사용합니다 [5]. IETF 언어 태그의 예는 다음과 같습니다: fr(프랑스어), ja(일본어), pt-BR(1943년 정서법 제정—브라질에서 공식적으로 사용됨).

URL에서는 밑줄보다 대시를 더 흔히 사용하므로 [6], sphinx가 내부적으로 gettext를 사용하더라도 IETF 언어 태그를 사용해야 합니다. URL은 기반 구현을 드러내도록 만들어진 것이 아니기 때문입니다.

URL에서 대문자를 보는 일은 드물며 docs.python.org도 대문자를 사용하지 않으므로, 다음과 같이 대문자가 시선을 끌어 가독성을 해칠 수 있습니다: “https://docs.python.org/pt-BR/3.6/library/stdtypes.html”. RFC 5646 Section 2.1.1 (Tags for Identifying Languages (IETF))의 section-2.1에서는 태그가 대소문자를 구분하지 않는다고 명시합니다. RFC에서 소문자를 허용하고 소문자가 가독성을 높이므로, pt-br과 같이 소문자로 된 태그를 사용해야 합니다.

지역 서브태그가 식별 정보를 추가하지 않는 경우에는 이를 생략할 수 있습니다. 예를 들어 “de-DE” 또는 “fr-FR”입니다. (각각 “독일에서 사용되는 독일어”와 “프랑스에서 사용되는 프랑스어”를 의미하므로 의미가 있을 수도 있습니다.) 그러나 지역 서브태그가 실제로 정보를 추가하는 경우, 예를 들어 “pt-BR” 또는 “브라질에서 사용되는 포르투갈어”인 경우에는 이를 유지해야 합니다.

따라서 /fr/, /pt-br/, /de/ 등과 같이 소문자로 된 IETF 언어 태그를 사용해야 합니다.

번역 가져오기 및 빌드하기

현재 docsbuild-scripts가 문서를 빌드하고 있습니다 [8]. 이러한 스크립트를 수정하여 번역을 가져오고 빌드하도록 해야 합니다.

새 번역을 빌드하는 작업은 새 버전을 빌드하는 작업과 같으므로, 복잡성이 추가되더라도 그 정도가 크지는 않습니다.

두 단계를 서로 독립적으로 구성할 수 있어야 합니다. 새 언어를 빌드하는 단계와 언어 전환기에 해당 언어를 추가하는 단계입니다. 이를 통해 “해당 언어를 수락한” 단계와 “공개하기에 충분히 번역된” 단계 사이에 전환 단계를 둘 수 있습니다. 이 단계에서 번역자는 문서를 로컬에서 빌드하지 않고도 d.p.o에서 자신이 수정한 내용을 검토할 수 있습니다.

번역 저장소에서는 공격 표면과 발생 가능성이 높은 버그 원인을 최소화하기 위해 docsbuild-script가 .po 파일만 열도록 해야 합니다. 이는 어떤 번역도 sphinx를 패치하여 자신의 번역 도구를 홍보할 수 없다는 의미입니다. (이 특정 기능은 어차피 sphinx에서 처리해야 합니다 [9].)

커뮤니티

메일링 리스트

번역된 문서의 언어 간 변경 사항을 논의하기 위해 doc-sig 메일링 리스트를 사용합니다.

i18n-sig 리스트도 있지만, Python 문서를 번역하는 것보다 i18n API에 더 중점을 둡니다 [1].

채팅

Python 커뮤니티는 IRC에서 매우 활발하므로, 메일링 리스트 이름과 일관되도록 일반적으로 #python-doc이라고 부르는 새 IRC 채널을 freenode에 만들어야 합니다.

각 언어 코디네이터는 현지 사용 환경에서 요구하는 경우 다른 채팅 시스템을 선택하는 것을 포함하여 자신의 팀을 조직할 수 있습니다. 지역 팀은 각자의 모국어로 작성하므로, 모든 팀을 하나의 채널에 두기를 원하지 않습니다. 또한 지역 팀이 프랑스어 번역자를 위한 “#python-fr”과 같은 현지 채널을 재사용하는 것도 자연스럽습니다.

PO 파일용 저장소

각 번역 팀이 서로 다른 번역 도구를 사용하고자 할 수 있으며 이러한 도구를 git과 쉽게 동기화할 수 있어야 하므로, 모든 번역은 git 저장소를 통해 자신의 .po 파일을 제공해야 합니다.

각 번역이 git 저장소를 통해 제공되고 Python이 GitHub로 이전했으므로, 번역은 GitHub에서 호스팅됩니다.

일관성과 검색 가능성을 위해 모든 번역은 동일한 GitHub 조직에 속하고 공통 패턴에 따라 이름을 지정해야 합니다.

번역을 공식적인 것으로 만들고자 하며 Python에 이미 GitHub 조직이 있으므로, 번역은 Python GitHub organization의 프로젝트로 호스팅해야 합니다.

일관성을 위해 번역 저장소는 python-docs-LANGUAGE_TAG [22]로 명명해야 하며, 경로에 사용되는 언어 태그를 사용하고 중복되는 지역 하위 태그는 제외하며 소문자로 표기해야 합니다.

docsbuild-scripts는 Python 조직 외부에 있거나 잘못된 이름의 저장소를 가져오지 않도록 거부함으로써 이 규칙을 강제할 수 있습니다.

CLA 봇은 번역 저장소에서 사용할 수 있지만, 로컬 코디네이터가 transifex와 같은 외부 도구의 번역을 자체적으로 동기화할 수 있으므로 그 과정에서 누가 무엇을 번역했는지 파악하지 못할 수 있어 효과가 제한적입니다.

버전은 서로 다른 저장소, 디렉터리 또는 브랜치에서 호스팅할 수 있습니다. 서로 다른 저장소에 저장하면 Python GitHub 조직이 아마도 오염될 것입니다. 버전을 분리하는 데 브랜치를 사용하는 것이 일반적이고 자연스러우므로, 이를 위해 브랜치를 사용해야 합니다.

번역 도구

실제 번역 작업의 대부분은 Transifex [15]에서 수행됩니다.

나중에는 https://pontoon.mozilla.org/ 및 http://zanata.org/ 같은 다른 도구를 사용할 수도 있습니다.

python-docs-translations

python-docs-translations GitHub organization은 translations.python.org(python-docs-translations/dashboard)를 비롯한 여러 유용한 번역 도구의 본거지입니다.

문서 기여 계약

문서에는 아이디어를 표현하는 과정에서 창의성이 개입되므로 번역자의 라이선스가 필요합니다.

이 주제에 대해 PSF의 Van Lindberg가 질문한 내용을 인용하면 여러 해결책이 있습니다.

문서는 저작권을 양도받거나 CCO에 따라 제공되어야 합니다. 허용적인 소프트웨어 라이선스(예: Apache 또는 MIT)를 사용해도 문제를 해결할 수 있지만, 이 작업에는 그다지 적합하지 않습니다.

번역자는 계약에 서명하거나 번역문과 함께 라이선스 선언서를 제출해야 합니다.

프로젝트 페이지에 사람들이 정의된 라이선스에 따라 기여하도록 초대하고, 기여 행위로 수락이 성립하도록 해야 합니다. 예를 들면 다음과 같습니다.

“이 프로젝트를 Transifex에 게시하고 귀하를 참여하도록 초대함으로써, 귀하가 CC0 라이선스에 따라 PSF가 사용할 수 있도록 번역을 제공한다는 계약을 제안합니다. 그 대가로 귀하는 자신이 번역한 부분의 번역자임을 표시할 수 있습니다. 문서에 포함할 수 있도록 귀하의 작업을 PSF에 제출함으로써 이 계약을 수락한다는 의사를 나타내게 됩니다.”

다양한 상황에서 기여자가 이에 동의하도록 보장하기 위해 여러 방법(GitHub 봇, 초대 페이지, …)을 사용할 수 있으므로, “문서 기여 계약”을 마련하는 것이 우리가 할 수 있는 가장 간단한 일인 것으로 보입니다.

언어 팀

각 언어 팀에는 다음 업무를 담당하는 코디네이터가 한 명 있어야 합니다.

팀을 관리합니다.
팀에서 사용할 도구(채팅, 메일링 리스트, …)를 선택하고 관리합니다.
기여자가 문서 기여 계약을 이해하고 이에 동의하도록 보장합니다.
품질(문법, 어휘, 일관성, 스팸 및 광고 필터링, …)을 보장합니다.
이슈 추적기에 게시된 이슈를 해당 언어의 올바른 GitHub 이슈 추적기로 전달합니다.

대안

쉬운 영어

Wikipedia가 했던 것과 같은 “간소화 영어” 버전을 [10]에서 소개하는 것도 가능합니다. python-dev [11]에서 논의된 것처럼 영어 학습자와 어린이를 대상으로 합니다.

장점: 이론적으로 모든 사람이 읽을 수 있고 현재 유지 관리자들이 검토할 수 있는 단일 번역을 만들어 냅니다.

단점: 미묘한 세부 사항이 사라질 수 있으며, Wikipedia가 설명한 것처럼 영어에서 영어로 번역할 번역자를 찾기 어려울 수 있습니다.

> 주 영어 Wikipedia에는 거의 14만 명의 활동 사용자가 작성한 500만 개의 문서가 있으며, 스웨덴어 Wikipedia도 활동 사용자가 3천 명뿐인데 300만 개의 문서로 거의 비슷한 규모입니다. 그러나 Simple English Wikipedia에는 12만 3천 개의 문서와 871명의 활동 사용자가 있을 뿐입니다. 이는 에스페란토보다도 적은 문서 수입니다!

변경 사항

문서 기여 계약 받기

문서 기여 계약은 PSF가 작성한 다음 https://www.python.org/psf/contrib/ 에 등록하고, https://www.python.org/psf/contrib/doc-contrib-form/ 과 같은 자체 페이지를 만들어야 합니다.

GitHub 저장소 마이그레이션

이 PEP의 작성자인 우리는 이미 프랑스어 및 일본어 Git 저장소를 소유하고 있으므로, 이를 Python 문서 조직으로 옮기는 데에는 문제가 없습니다. 그러나 New Translation Procedure를 따릅니다.

문서 기여 계약용 GitHub 봇 설정

GitHub의 기여자들이 문서 기여 계약에 서명했는지 확인하는 데 도움을 주기 위해, 마이그레이션된 저장소 [28]에서 이 계약에 맞게 사용자 정의한 “The Knights Who Say Ni” GitHub 봇을 설정할 수 있습니다.

번역을 컴파일하도록 docsbuild-scripts 패치

Docsbuild-script를 다음과 같이 패치해야 합니다:

빌드할 브랜치와 함께 빌드할 언어 태그를 나열해야 합니다.
언어 전환기에 표시할 언어 태그를 나열해야 합니다.
github.com:python/python-docs-{language_tag}.git 형식을 사용하여 번역 저장소를 찾아야 합니다(Repository for PO Files 참조).
각 브랜치와 각 언어의 번역을 빌드해야 합니다.

패치된 docsbuild-scripts는 번역 저장소의 .po 파일만 열어야 합니다.

NOTE REGARDING THE LICENSE FOR TRANSLATIONS: Python's documentation is
maintained using a global network of volunteers. By posting this
project on Transifex, GitHub, and other public places, and inviting
you to participate, we are proposing an agreement that you will
provide your improvements to Python's documentation or the translation
of Python's documentation for the PSF's use under the CC0 license
(available at
`https://creativecommons.org/publicdomain/zero/1.0/legalcode`_). In
return, you may publicly claim credit for the portion of the
translation you contributed and if your translation is accepted by the
PSF, you may (but are not required to) submit a patch including an
appropriate annotation in the Misc/ACKS or TRANSLATORS file. Although
nothing in this Documentation Contribution Agreement obligates the PSF
to incorporate your textual contribution, your participation in the
Python community is welcomed and appreciated.

You signify acceptance of this agreement by submitting your work to
the PSF for inclusion in the documentation.