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년에 기여자 7명 [14]과 함께 6%에서 23%로 늘어났으며 [13], 이는 번역 팀이 문서가 변경되는 속도보다 더 빠르게 작업할 수 있음을 보여 줍니다.

중국어 번역에 관한 Xiang Zhang의 말을 인용합니다:

저는 우리 공식 문서의 일부를 번역하려는 여러 그룹을 보았습니다. 하지만 그들의 노력은 하나의 공통된 결과를 목표로 조직되어 있지 않고 결과물도 웹 여기저기에 흩어져 있어 찾기 어렵기 때문에, 분산되어 금세 사라져 버립니다. 공식 번역이 있다면 이러한 어려움을 덜 수 있을 것입니다.

근거

번역

이슈 트래커

번역에 관해 등록된 이슈는 번역 대상 언어로 작성될 수 있으며, 이는 노이즈로 여겨질 수 있고 적어도 일관성이 없으므로, 이슈를 CPython 이슈 트래커에 등록해서는 안 됩니다.

모든 번역은 각자의 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 인증서를 만들어야 합니다. 이는 유지 보수 부담을 늘릴 뿐 아니라, 버전 전환기처럼 해당 버전에 번역이 존재하는지 확인하는 사전 요청(preflight)을 하려는 경우 언어 전환기에도 문제를 일으킵니다. 사전 요청은 동일 출처 정책(same-origin-policy)에 의해 차단될 가능성이 높습니다. 와일드카드 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 언어 태그 [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에서 매우 활발하게 활동하고 있으므로, freenode에 새 IRC 채널을 만들어야 하며, 메일링 리스트 이름과의 일관성을 위해 보통 #python-doc으로 합니다.

각 언어 코디네이터는 자신의 팀을 자유롭게 꾸릴 수 있으며, 현지 사용 관행상 필요하다면 다른 채팅 시스템을 선택할 수도 있습니다. 현지 팀들은 각자의 모국어로 글을 쓸 것이므로, 모든 팀을 하나의 채널에 모으는 것은 바람직하지 않습니다. 현지 팀이 프랑스어 번역자를 위한 “#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 조직에는 translations.python.org (python-docs-translations/dashboard)를 비롯한 여러 유용한 번역 도구가 있습니다.

문서 기여 동의서

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

해결책은 여러 가지가 있습니다. 이 주제에 관해 질문을 받은 PSF의 Van Lindberg의 말을 인용합니다:

문서는 저작권을 양도받거나 CCO 아래에 두어야 합니다. (Apache나 MIT 같은) 허용적 소프트웨어 라이선스로도 목적을 달성할 수 있지만, 이 작업에 딱 맞지는 않습니다.

번역자는 동의서에 서명하거나, 번역과 함께 라이선스 선언을 제출해야 합니다.

프로젝트 페이지에 정해진 라이선스로 기여해 달라는 안내를 두고, 기여 행위 자체를 동의로 간주하도록 해야 합니다. 예를 들면 다음과 같습니다:

“이 프로젝트를 Transifex에 게시하고 여러분의 참여를 요청함으로써, 저희는 여러분이 CC0 라이선스에 따라 PSF가 사용할 수 있도록 번역을 제공한다는 동의를 제안합니다. 그 대가로 여러분은 자신이 번역한 부분의 번역자임을 명시할 수 있습니다. 여러분은 문서에 포함되도록 작업물을 PSF에 제출함으로써 이 동의를 수락하는 것으로 간주됩니다.”

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

언어 팀

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

팀을 관리합니다.
팀이 사용할 도구(채팅, 메일링 리스트, …)를 선택하고 관리합니다.
기여자가 문서 기여 동의서를 이해하고 이에 동의하도록 합니다.
품질(문법, 어휘, 일관성, 스팸 및 광고 걸러내기, …)을 보장합니다.
이슈 트래커에 올라온 이슈를 해당 언어의 올바른 GitHub 이슈 트래커로 넘깁니다.

대안

단순화된 영어

위키백과가 그랬듯이 [10], python-dev에서 논의된 것처럼 [11], 영어 학습자와 어린이를 대상으로 하는 “쉬운 영어(simplified English)” 버전을 도입할 수도 있습니다.

장점: 번역이 하나만 만들어지며, 이론적으로 누구나 읽을 수 있고 현재 유지 관리자들이 검토할 수 있습니다.

단점: 미묘한 세부 사항이 사라질 수 있으며, 위키백과에서 언급했듯이 영어를 영어로 옮길 번역가를 찾기 어려울 수 있습니다:

> 영어 위키백과 본판에는 약 14만 명의 활동 사용자가 작성한 문서 500만 개가 있습니다. 스웨덴어 위키백과도 거의 그만큼 커서, 불과 3천 명의 활동 사용자가 문서 300만 개를 작성했습니다. 하지만 쉬운 영어 위키백과에는 문서 12만 3천 개와 활동 사용자 871명뿐입니다. 에스페란토보다도 문서가 적습니다!

변경 사항

문서 기여 동의서 마련하기

문서 기여 동의서(Documentation Contribution Agreement)는 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 기여자들이 문서 기여 동의서에 서명했는지 확인하는 데 도움이 되도록, 이전된 저장소에 이 동의서에 맞게 사용자 정의한 “The Knights Who Say Ni” GitHub 봇을 설정할 수 있습니다 [28].

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

Docsbuild-script는 다음 작업을 하도록 패치되어야 합니다:

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

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

devguide에 코디네이터 목록 작성하기

devguide에 비어 있는 코디네이터 목록을 담은 페이지나 섹션을 추가하고, 새 코디네이터가 생길 때마다 이 목록에 추가합니다.

sphinx-doc 언어 전환기 만들기

버전 전환기와 매우 비슷한 언어 전환기를 구현해야 합니다. 이 언어 전환기는 특정 언어를 숨기거나 표시하도록 설정할 수 있어야 합니다.

언어 전환기는 현재 버전 전환기가 하는 것처럼 경로의 언어 세그먼트를 갱신하거나 추가하기만 하면 됩니다. 버전 전환기와 달리, 대상 페이지가 항상 존재하므로 사전 확인(preflight)이 필요하지 않습니다(번역은 페이지를 추가하거나 제거하지 않습니다). 번역되지 않은 (그러나 존재하는) 페이지도 여전히 존재하지만, 번역되지 않았음이 드러나도록 렌더링되어야 합니다. Enhance Rendering of Untranslated and Fuzzy Translations를 참조하십시오.

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.