0006. 문서는 영어가 정본이고, 한국어판을 함께 둔다¶

상태: 채택
날짜: 2026-10-14

배경¶

문서 사이트(연구자 안내서, 튜토리얼, How-to, 계약서, 설계 결정)는 연구실 구성원을 위해 한국어로 쓰였고 완성도가 높았다. 논문·프리프린트·Zenodo DOI로 들어오는 독자는 영어로 읽는다. 한국어판은 버리기 아까울 만큼 잘 만들어져 있었다. 자동 생성 레퍼런스(명령, 파이썬 함수, 설정 키, 갤러리)는 이미 영어였다.

결정¶

영어가 사이트의 기본 언어이자 정본이고 /에 있다. 한국어판은 그 옆, /ko/에 있고 모든 페이지에서 전환 버튼 하나로 오간다(mkdocs-static-i18n).
페이지의 한국어판은 page.md 옆의 page.ko.md이고, 두 판이 같은 그림을 쓴다. 메뉴 제목은 영어이고 한국어 제목은 nav_translations에 둔다.
페이지를 고치면 같은 커밋에서 두 판을 함께 고친다(AGENTS.md).
범위 밖: 자동 생성 레퍼런스의 한국어판, AGENTS.md와 스킬 문서의 번역.
용어는 원고를 따른다(bundle, renderer, config, figure spec, preflight, provenance record, live numbers, ...).

결과¶

논문에서 온 독자는 영어 페이지에 닿고, 연구실은 한국어 페이지를 그대로 쓴다.
검색은 언어별이다. 플러그인은 두 언어를 색인 하나에 담는데, 사이트 훅(scripts/mkdocs_hooks.py)이 빌드 뒤에 나눈다. 영어 사이트는 영어 페이지를, 한국어 사이트는 한국어 페이지(와 한국어판이 없는 영어 레퍼런스 페이지)를 찾는다.
두 판은 어긋날 수 있다. 붙잡아 두는 장치:
tests/test_docs_i18n.py: 한국어 페이지에는 영어 페이지가 있어야 하고, 제목 수준, 코드 블록(산문인 주석, 도표,  표시 블록 제외), 튜토리얼 단계 표시, 그림, 표, 링크 대상이 같아야 한다.
tests/test_tutorials.py는 영어 튜토리얼을 실행한다. 실행 단계가 한국어판과 글자 그대로 같으므로 두 판 모두 같은 결과를 약속한다.
docs/i18n_pending.txt는 아직 영어판이 없는 페이지 목록이고(번역을 마친 뒤 비어 있음), 테스트가 이 목록을 정확하게 유지한다.
구조는 검사하지만 문장은 검사하지 않는다. 두 판의 문장이 같은 말을 하는지는 검토에 맡긴다.