파이썬 번역 리부트

Python
공개

2025-04-19

초록

파이썬 번역 프로젝트를 리부트한다. 3.13 번역을 준비한다. 브라우저만으로 작업할 수 있도록, 도구를 현대화한다.

작업의 범위와 방향

현재 번역자들에게 제시하는 가이드 문서는 https://www.flowdas.com/pages/python-docs-ko.html 다. 이 문서의 내용은 크게 3가지다.

  • 관련 자원들에대한 링크와 설명.
  • 개발 가이드
  • 용어집

이 문서에서는 번역 지원 도구를 언급하고 있다. GitHub 공개 저장소 https://github.com/flowdas/python-docs-ko 에서 관리되고 있다.1 이 CLI 도구가 제공하는 명령은 4개다.

  • init - 환경 설정.
  • build - 번역을 렌더링해서 html 을 생성.
  • format - .po 파일을 표준 형식으로 포매팅.
  • spell - 맞춤법 검사.

번역자들이 GitHub 에서 3.13 번역 이슈를 골라서 작업한 후 PR 을 보낼 수 있도록 재정비한다.

이번 작업의 범위와 방향을 결정하는 세부 기준은 다음과 같다.

  • 개발 컨테이너를 지원한다.
  • 개발자가 다른 곳을 기웃거릴 필요 없도록, 가이드 문서와 번역 지원도구 모두 공식 저장소로 옮긴다.
  • 맞춤법 검사 기능은 이번 작업에서 제외한다.2
  • 3.13 번역을 시작할 수 있는 조건을 만든다.
  • 실용성과 단순화를 선호하고 일반화를 지양한다.

개발 컨테이너

번역할 때 가장 큰 걸림돌은 아마도 프리뷰일 것이다. .po 파일에 자신의 번역을 담아내면, PR을 보내기 전에 프리뷰를 통해 이상이 없는지 확인해야 한다.

현재 사용 중인 개발 지원 도구는 flowdas/python-docs-ko 저장소에서 관리되고 있다. 빌드 스크립트를 실행하기위해 사전에 설치할 것들도 있고, Windows 용 빌드 스크립트가 없어서, 도구는 내부적으로 도커 이미지를 활용하고 있다. 이 도구가 좀 낡기도 했고, Docker Desktop 의 사전 설치를 요구해서, 시작할 때 거쳐야할 단계를 어려워하는 분들이 있다.

GitHub Codespaces 로 바로 시작할 수 있는 환경을 제공한다면, 사전 설치 요건이 제거된다. 브라우저 만으로도 작업할 수 있게되어, Cellular iPad mini 만으로 작업한다는 오랜 숙원을 마침내 이룰 수 있게된다. GitHub 무료 계정에서도 어느 정도의 Codespaces 사용량을 제공하니, 비용 문제도 발생하지 않을것으로 보인다. Codespaces 가 싫으면 vscode 로 로컬 개발 컨테이너를 사용할 수도 있다.

3.13 브랜치에 컨테이너 설정을 넣는다.

.devcontainer/devcontainer.json
{
    "name": "python-docs-ko",
1    "image": "mcr.microsoft.com/devcontainers/python:3.13",
2    "postCreateCommand": "pip install --user -e .pdk; pdk init",
    "containerEnv": {
3        "PDK_BRANCH": "3.13",
4        "PDK_REVISION": "db7ad1c89f8b8f0319ec2f3a20f2f3c226a406ed"
    },
    "features": {
5        "ghcr.io/devcontainers/features/github-cli:1": {}
    },
    "customizations": {
        "vscode": {
            "extensions": [
6                "mrorz.language-gettext",
7                "charliermarsh.ruff",
8                "donjayamanne.githistory"
            ]
        }
    }
}
1
번역할 버전과 사용할 버전을 일치시킨다.
2
.pdk 디렉터리에 패키지 소스코드가 들어있어서, init 라는 초기화 명령을 제공하는 pdk 스크립트가 설치된다. 빌드에 필요한 패키지들도 이 때 설치된다. 설치 후 pdk init 로 빌드 환경을 구축한다.
3
3.13 버전을 번역한다.
4
po 파일을 만들 때 사용한 리비전으로 빌드한다.
5
GitHub CLI
6
po 파일의 구문 하일라이트를 위한 확장.
7
.pdk 디렉터리의 파이썬 소스 코드는 ruff 로 포매팅한다.
8
가끔 git history 보고 싶을 때를 위해서.

postCreateCommand 로 지정한 명령은 컨테이너 이미지가 만들어진 직후 한 번만 실행된다. 이 때 root 권한이 없어서 --user 옵션을 준다. -e 옵션을 주었으니 pdk 버전이 올라갈 때마다 컨테이너를 리빌드할 필요는 없다. 하지만 init 명령이 변경될 때는 리빌드해야 한다.

pdk

이제 pdk 패키지의 프로젝트 파일을 넣는다.

.pdk/pyproject.toml
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "pdk"
version = "0.1.0"
description = "python-docs-ko tools"
authors = [
    {name = "Paul Oh", email = "flowdas@gmail.com"},
]
dependencies = [
1    "blurb==2.0.0",
    "python-docs-theme==2025.2",
    "sphinx==8.2.3",
    "sphinx-intl==2.3.1",
2    "fire==0.7.0",
]
requires-python = ">=3.13"

3[project.scripts]
pdk = "pdk:main"

4[tool.setuptools]
packages = ["pdk"]
1
빌드에 필요한 패키지
2
CLI 라이브러리
3
main 함수를 호출하는 pdk 스크립트를 설치한다.
4
pdk 패키지에 소스 코드를 넣는다.

범용으로 배포할 패키지가 아니라서 모든 디펜던시들은 버전을 고정했다.

CLI 는 Python Fire 를 사용한다.

.pdk/pdk/__init__.py
import fire


class Command:
1    def init(self):
        """Initialize .pdk."""
        pass


def main():
    fire.Fire(Command)
1
init 명령. 일단 자리만 만들어둔다.

이정도면 에러 없이 Codespaces 가 뜬다. 빌드 시스템이 불평하지는 않는지 하루 정도 두고보자.

init

init 명령을 살펴보자. 사용자가 직접 실행하는 명령은 아니다. 컨테이너가 만들어질 때 한 번만 실행되어 빌드 환경을 초기화한다.

파이썬 소스 트리

먼저 /workspaces/cpython 에 파이썬 소스 트리를 clone 한다.3 브랜치를 환경 변수 PDK_BRANCH 로 지정한 브랜치로 설정한다. 관리자가 po 파일을 만들 때 사용한 소스 트리와, 번역자가 프리뷰 빌드를 할 때 사용하는 소스 트리를 일치시키기 위해 환경 변수 PDK_REVISION 로 지정한 리비전으로 고정한다. 대략 이런 명령을 사용하면 된다.

git clone --single-branch -b ${PDK_BRANCH} https://github.com/python/cpython
cd cpython
git checkout ${PDK_REVISION}

LC_MESSAGES

그런 다음, 메시지 디렉터리를 설정해서 번역한 po 파일들이 빌드할 때 사용되도록 설정한다. /workspaces/python-docs-ko 를 가리키도록 심볼릭 링크 /workspaces/cpython/Doc/locales/ko/LC_MESSAGES 를 만들면 된다.

빌드

flowchart LR
  A[.rst] -- extract --> B[.pot]
  B -- update --> C[.po]
  C -- build or watch --> D[.html]
그림 1: 파일 변환 흐름과 관련 명령들.

그림 1 은 파일 변환의 각 단계에 사용하는 명령을 보여주고 있다.

각 명령들은 /workspaces/cpython/Doc 디렉터리에서 간단한 쉘 명령을 실행한다.

make gettext                                    # extract
sphinx-intl update -p build/gettext -l ko       # update
make -e SPHINXOPTS="-D language='ko'" html      # build
make -e SPHINXOPTS="-D language='ko'" htmllive  # watch

저장소에는 이미 .po 파일들이 준비된 상태이기 때문에, 마지막 단계를 바로 실행해서 렌더링된 페이지를 얻을 수 있다. build 는 /workspaces/cpython/Doc/build/html 디렉터리에 .html 을 출력하고, watch 는 라이브 프리뷰를 제공한다. 처음 빌드할 때는 무척 오래걸린다.4

관리자는 extract 와 update 명령을 정기적으로 사용하여 번역자들을 지원한다. update 명령이 수행하는 변환 작업은 단순 복사가 아니다. 작업 디렉터리에 있는 .po 파일과 .pot 파일을 비교해서 기존 .po 파일에 들어있는 번역을 최대한 보존하려고 시도한다. 이 명령을 실행하기 전에 작업 디렉터리에 커밋하지 않은 변경이 없도록 주의해야 한다.

format

format 명령은 .po 파일이 표준 형식을 갖추도록 변환한다.

번역 가이드

번역 가이드는 .pdk/guide.md 로 옮긴다.

3.13 용 .po 파일 생성

pdk extract 한 후 pdk update 한다. 상당히 긴 목록이 출력된다. 이 목록을 보면 43개의 신규 파일이 생기고, 430개의 파일이 변경되었음을 알 수 있다. 한편 이 목록이 삭제해야할 파일을 알려주지는 않는다.

같은 이름의 .pot 파일이 없는 .po 파일들을 찾아주는 pdk find_obsoletes 명령의 출력은 이렇다.

distutils/index.po
distutils/packageindex.po
distutils/builtdist.po
distutils/configfile.po
distutils/_setuptools_disclaimer.po
distutils/introduction.po
distutils/uploading.po
distutils/extending.po
distutils/apiref.po
distutils/examples.po
distutils/setupscript.po
distutils/sourcedist.po
distutils/commandref.po
library/symbol.po
library/undoc.po
library/misc.po
library/dummy_threading.po
library/tkinter.tix.po
library/binhex.po
library/2to3.po
library/formatter.po
library/_dummy_thread.po
library/othergui.po
library/parser.po
install/index.po
c-api/objbuffer.po

확인 후에 -d 옵션을 주고 다시 실행하면 파일들을 삭제한다. pdk find_obsoletes -d.

이 파일들에 해당하는 이슈가 남아있는지 확인하고 지워준다. 찾아보니 파일 3개가 이런 경우다.5

library/tkinter.tix.po
library/formatter.po
library/parser.po

이슈 삭제한다.

3.13 브랜치로 추가/변경/삭제된 .po 파일들을 푸시한다.

이슈 등록

이제 43개의 신규 파일과 430개의 변경에 대한 이슈를 등록해야한다. 430개의 변경중 일부는 남아있는 21개의 이슈와 겹칠 수 있어서 골라내야한다. 어쨌거나 손으로 등록하기에는 좀 많다. 앞서 얻은 목록으로 GitHub CLI 로 이슈를 등록하는 스크립트를 만드는 방식으로 처리한다.

맺음말

파이썬 3.13 번역에 필요한 준비를 마친다. Codespaces 를 쓸 수 있어서 개발 환경이 약간 개선되었지만, 그 외에는 과거의 개발 환경을 복원하는데 집중했다. 몇가지는 남겨두었다.

  • 맞춤법 검사기는 재검토 후 도입 여부를 결정할 것이다. 다른 제품을 선택하게 될 가능성도 있다.
  • 외부 인프라 의존성을 모두 제거하는 과정에서 프로젝트의 진척도 표시도 함께 제거되었다. 이 역시 적절한 방법을 찾아서 다시 넣는 것이 좋을 것이다.

3.9 에서 초벌 번역을 완료했다. 사실은 3.4 와 그 이전의 whatsnew 들이 남아있었지만, 너무 재미없어서 그냥 끝난 것으로 선언해버렸다. 3.13 을 리부트하고 보니, 새 문서가 43개 생겼는데, 꽤 재미있는 것들이 있다. 하지만 대단한 규모는 아니다. 변경된 파일들은 430개인데, 이들은 부분 변경이라서 역시 엄청난 규모는 아니다. 때문에 이제부터는 초벌 번역을 넘어 편집에 들어갈 때다.

편집은 훨씬 어려운 작업이다. 일종의 QA 단계로 볼 수 있는데, 무엇보다도 “편집 원칙”이 서야한다. 혼자하려면 잘하건 못하건 알아서 하면 그만이다. 하지만 편집 기여를 받으려면 혹은 함께 편집하려면 어떤 원칙을 새우고, 어떤 프로세스를 취해야할까? 이 문제는 아직 풀지 못했다. 어디에 도착하게 될지는 모르겠으나 한 걸음 다시 내딛는다.

각주

  1. 저장소가 너무 많아서 틈나는데로 삭제하고 있다. 이 저장소 역시 작업을 마무리한 후에는 삭제할 가능성이 높다. 없다고 놀라지 마시기를.↩︎

  2. 맞춤법 검사는 부산대학교 인공지능연구실과 (주)나라인포테크가 제공하는 서비스를 활용하고 있다. 이제 개인 저장소가 아닌 PSF 의 저장소로 옮기기 때문에, 허가 없는 사용에 문제는 없을지 재검토가 필요하다.↩︎

  3. 처음에는 /workspaces/python-docs-ko/.pdk/cpython 에 clone 하려고 했다. 하지만 이렇게하면 뒤에 나오는 LC_MESSAGES 심볼릭 링크 때문에 소스 트리상에 루프가 형성되어 문제를 일으킨다.↩︎

  4. 빌드할 때 multiprocessing 을 사용하니 코어 수를 늘리면 도움이 될 수도 있다.↩︎

  5. 버전 3.9 에서 오래된 whatsnew 와 삭제가 예고된 파일들을 제외하고 초벌 번역은 완료했다. 그래서 whatsnew 를 빼고는 모두 지워질 이슈만 남아있다. 그런데 고작 3개만 지워지는구만. 나머지는 언제 지우나? smtpd 를 확인해보니 삭제되었다는 안내가 들어있다. 지워지지는 않을 모양이구만.↩︎