.. python-docs-ko documentation master file
python-docs-ko
==============
Version |version|.
`python-docs-ko `_ 패키지는 파이썬 공식 설명서의 한국어 번역 작업을
지원하는 도구입니다. 파이썬 한국어 번역팀이 사용하고 있습니다. 주요 기능은 이렇습니다.
* 프리뷰 빌드
* 철자 검사
* 번역한 문서의 표준 포매팅
Prerequisites
-------------
이 도구를 설치하고 사용하기 위해서 필요한 사전 요구 사항이 있습니다.
* 파이썬 3.7+
* Git
* Docker
* https://github.com/python/python-docs-ko 의 Fork
세 가지 도구 모두 설치되고, ``PATH``\에 경로가 설정되어 있어야 합니다.
Docker의 사용법을 꼭 알아야 하는 것은 아닙니다. 설치되어 있기만 하면 됩니다.
https://github.com/python/python-docs-ko 는 파이썬 한국어 번역의 공식 git 저장소입니다.
번역 작업을 위해서는 이 저장소를 fork 해야 합니다.
Install
-------
셸에서 다음과 같이 실행합니다::
python3.7 -m venv
cd
source bin/activate
pip install python-docs-ko
pdk init
```` 이라는 디렉터리에 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
-----
번역이 마무리되면 철자 검사를 해야 합니다.
.. toctree::
:maxdepth: 2
:caption: Contents:
::
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을 보내셔도 됩니다.
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`