Weblate

Weblate 는 웹 기반 번역 플랫폼입니다. 본 프로젝트의 한글 문서는 한국어를 원문으로 하고, Weblate 를 통해 영어로 번역됩니다.

• 번역 인스턴스: https://translate.openinfra.kr

• 프로젝트 / 컴포넌트: openstack-kubernetes / docs

• 원문 언어: 한국어(ko) → 번역 언어: 영어(en)

실제 번역하는 방법은 Weblate 번역 가이드 를 참고하세요. 이 문서는 번역이 자동으로 동기화되는 구조를 설명합니다.

전체 흐름

원문/문자열은 GitHub → Weblate(①)로, 번역 결과는 Weblate → GitHub(②)로 흐릅니다.

핵심: Weblate 는 .po 를 읽고 씁니다

Weblate 는 RST 원문을 직접 다루지 않습니다. Sphinx 문서는 gettext 방식으로 번역되며, 번역 단위는 .po 파일입니다.

doc/source/**/*.rst (한국어 원문)
     |  Sphinx 로 추출 (tox -e update-po)
     v
doc/source/locales/en/LC_MESSAGES/docs.po   <- Weblate 가 읽고 씀
     |  Sphinx 빌드 (-D language=en)
     v
영어 HTML (/en/)

• 번역 대상 문자열은 원문에서 추출되어 docs.po 의 msgid 가 됩니다.

• 번역 결과는 docs.po 의 msgstr 에 저장됩니다.

• 그래서 원문이 바뀌면 .po 를 다시 생성해야 새 문장이 Weblate 에 나타납니다(아래 ① 자동화).

참고

conf.py 에서 gettext_compact = 'docs' 로 설정해 모든 문서를 하나의 docs.po 로 합칩니다. 덕분에 새 .rst 문서를 추가해도 그 문장이 같은 카탈로그에 들어가 Weblate 컴포넌트 하나가 자동으로 포착합니다.

① GitHub → Weblate (원문/문자열 반영)

저장소 원문이 바뀌면 Weblate 에 반영됩니다. 두 단계로 동작합니다.

1단계 — 카탈로그 자동 재생성 (GitHub Actions)

doc/source/**.rst 또는 conf.py 가 main 에 들어오면 워크플로우 .github/workflows/i18n-sync.yml 이 실행됩니다.

tox -e update-po     # .pot 추출 + docs.po 갱신(기존 번역 보존)
-> 변경이 있으면 docs.po 를 자동 커밋

sphinx-intl update 는 내부적으로 msgmerge 를 수행하여 기존 번역은 유지하면서 새 문장 추가/삭제/변경을 처리합니다.

2단계 — Weblate 가 변경을 받아옴 (Webhook)

저장소의 Webhook 이 push 때마다 Weblate 알림 엔드포인트로 신호를 보냅니다.

GitHub(push) --POST--> translate.openinfra.kr/hooks/github/
                       -> Weblate 가 pull -> 새 문자열 노출

• 이 엔드포인트는 인증이 필요 없습니다. Weblate 는 payload 의 저장소를 기존 컴포넌트와 대조한 뒤, 컴포넌트에 등록된 신뢰된 URL 에서만 pull 합니다.

• 저장소가 공개라 Weblate 는 익명으로 읽습니다.

② Weblate → GitHub (번역 결과 반영)

번역가가 저장한 번역이 다시 저장소로 돌아갑니다.

Weblate 에서 번역 저장
     v
Weblate 가 docs.po 커밋 (지연 커밋: 일정 시간/분량마다 묶음)
     v
weblate-translations 브랜치로 push   (인증: GitHub PAT)
     v
Pull Request 자동 생성/갱신
     v
메인테이너 리뷰 후 머지
     v
GitHub Actions 가 영어 문서 빌드 -> 배포 (/en/)

• Weblate 가 push/PR 하려면 쓰기 권한 인증이 필요하며, 서버 환경변수의 개인 액세스 토큰(PAT)을 사용합니다.

• 번역은 묶음(지연 커밋)으로 처리되어 하나의 PR 이 점진적으로 갱신됩니다.

인증 정리 (방향별)

동작	인증	비고
GitHub → Weblate (Webhook)	불필요	공개 엔드포인트
Weblate 가 저장소 읽기(pull)	불필요	저장소 공개
Weblate → GitHub (push/PR)	PAT 필요	서버 환경변수
Actions 의 카탈로그 커밋	GITHUB_TOKEN	별도 시크릿 없음

컴포넌트 설정 요약

항목	값
원문 언어	한국어 (ko)
번역 언어	영어 (en)
파일 형식	gettext PO (bilingual)
File mask	doc/source/locales/*/LC_MESSAGES/docs.po
버전 관리	github (PR 방식), merge: rebase
Push 브랜치	weblate-translations

메인테이너 메모

참고

• 원문을 바꿨는데 Weblate 에 안 보이면, ①의 카탈로그 재생성 Action 이 돌아 docs.po 가 갱신됐는지, Webhook 이 전달됐는지 확인합니다.

• filemask 등을 바꾼 뒤 재스캔이 안 되면(이미 파싱됨으로 스킵), 서버에서 weblate loadpo --force --foreground openstack-kubernetes/docs 로 강제 재로딩합니다.

• 로컬 미반영 커밋과 원격이 어긋나면 Weblate 의 Repository 에서 reset 으로 원격 상태에 맞춥니다.