python-docs-ko¶
Version 1.1.
python-docs-ko 패키지는 파이썬 공식 설명서의 한국어 번역 작업을 지원하는 도구입니다. 파이썬 한국어 번역팀이 사용하고 있습니다. 주요 기능은 이렇습니다.
프리뷰 빌드
철자 검사
번역한 문서의 표준 포매팅
Prerequisites¶
이 도구를 설치하고 사용하기 위해서 필요한 사전 요구 사항이 있습니다.
파이썬 3.7+
Git
Docker
세 가지 도구 모두 설치되고, PATH에 경로가 설정되어 있어야 합니다.
Docker의 사용법을 꼭 알아야 하는 것은 아닙니다. 설치되어 있기만 하면 됩니다.
https://github.com/python/python-docs-ko 는 파이썬 한국어 번역의 공식 git 저장소입니다. 번역 작업을 위해서는 이 저장소를 fork 해야 합니다.
Install¶
셸에서 다음과 같이 실행합니다:
python3.7 -m venv <work-dir>
cd <work-dir>
source bin/activate
pip install python-docs-ko
pdk init <your-python-docs-ko-fork>
<work-dir> 이라는 디렉터리에 venv 가상 환경을 만들고, python-docs-ko 패키지를 설치합니다.
이 패키지는 pdk 라는 콘솔 응용 프로그램을 제공하는데, init 명령으로 작업 환경을 구성합니다.
init 명령에 여러분이 fork 한 저장소의 URL을 제공하면, python-docs-ko라는 이름의 디렉터리가 만들어집니다.
(앞으로 python-docs-ko라는 이름의 디렉터리를 언급하면 이 디렉터리를 뜻합니다.)
그 밑에 여러분의 git 저장소가 msg 라는 이름의 디렉터리로 clone 됩니다. 번역 작업은 이곳에 있는 *.po 파일을
편집함으로써 수행됩니다.
PR을 머지할 때 squash 하므로, 번역작업마다 별도의 브랜치를 만들어서 작업하셔야 업스트림을 머지할 때 컨플릭트가 발생하지 않습니다.
Build¶
어느 정도 번역이 진행되면 프리뷰를 빌드해서 문제가 없는지 살펴야 합니다.
pdk build
처음에는 상당히 오래 걸리지만(제 맥북에서는 6분 정도 걸립니다), 두 번째부터는 변경된 파일만 빌드하기 때문에 금방(제 맥북에서는
30초 정도 걸립니다) 끝납니다. 빌드된 HTML 파일들은 python-docs-ko/bld/html 디렉터리에 만들어집니다.
Spell¶
번역이 마무리되면 철자 검사를 해야 합니다.
pdk spell POFILE
번역한 po 파일의 경로를 POFILE 로 제공하면 됩니다. 그러면 검사 결과를 python-docs-ko/../spell.txt
파일에 저장합니다. 예를 들면 이렇습니다.
# sorting.po:106
어트리뷰트를 -> 속성을: 외래어보다는 순수 우리말이나 한자어로 된, 우리가 자주 쓰는 말을 사용합시다.
sorting.po 파일의 106번째 줄에 있는 msgid 의 번역에 나오는 어트리뷰트를 이라는 구절을 속성을 로 바꿀 것을
제안하고 있고, 그 이유는 외래어보다는 ...입니다.
이 예에서 드러나듯이, 번역팀이 따르지 않는 제안도 많기 때문에 사용자가 보고 직접 결정을 내려야만합니다.
이 철자 검사기는 http://speller.cs.pusan.ac.kr/ 를 사용하고 있습니다. 서비스에 과부하를 주지 않기 위해 메시지별로 5초 간격으로
요청을 보냅니다. 그래서 새 번역에 대해 처음 실행하면 꽤 오래걸립니다. 하지만 한번 보낸 요청은 캐싱해서 다시 보내지 않기 때문에, 두 번째 실행
부터는 바뀐 메시지만 검사합니다. 하지만 spell.txt 파일은 항상 전체 메시지에 대해 만들어집니다.
Format¶
철자 검사와 교정이 마무리되면, PR을 보내기 전에 po 파일을 포매팅합니다.
pdk format POFILE
사용법은 spell 명령과 비슷합니다만, POFILE 을 표준 양식으로 포매팅합니다. 이렇게해야 리뷰 프로세스가 수월해지고,
몇가지 잘못될 가능성을 사전에 방지할 수 있습니다.
헤더에 번역팀을 삽입하고, 번역되지 않고 남은 메시지가 없는지 확인하기도 합니다.
번역이 필요 없이 원문 그대로 사용해도 무방한 메시지들도 있습니다. 그럴 때 msgstr 을 그대로 두기도 하는데,
불행히도 format은 번역을 안 한 것인지, 필요가 없는 것인지 구별할 능력이 없습니다. 필요 없어도
msgstr을 채워주시는 편이 좋습니다.
이 작업까지 끝나면 PR을 보내셔도 됩니다.