ADR 0003: 언어 정책 — 코드·커밋·README 는 영어, 이슈는 한국어 허용¶
상태¶
제안됨(Proposed) — 결정 대기
요약 (English summary)¶
Code, comments, docstrings, commit messages, issue and PR titles and CHANGELOG are English. Issue bodies, PR bodies and review comments may be written in Korean or English. README is two files:
README.mdin Korean andREADME.en.mdin English, kept structurally in step by a CI check. Korean-language documentation is kept where the subject matter is Korean (provider procedures, KOGL terms), and user-visible strings are out of scope — their language is runtime behaviour, decided separately.The aim is to keep the entry barrier low for the Korean contributors who are here now, while not making the project unreadable to anyone who is not.
배경¶
이 프로젝트는 한국 공공데이터를 다루므로 도메인이 한국에 묶여 있다. 동시에 글로벌 오픈소스로 공개하려 한다. 두 사실이 언어 정책에서 정면으로 만난다.
- 활용신청, 법정동코드, 공공누리 유형, 기관별 특이사항은 한국어로 써야 정확하다. "활용신청" 을 "application for use" 로 쓰면 그것이 어떤 절차인지 사라진다.
- 반면
help()와 API 문서에 나오는 docstring 이 한국어면, 한국어를 모르는 사람은 라이브러리를 읽을 수 없다.
기존 정책은 "코드는 한국어 우선" 이었고, 이것이 두 번째 문제를 그대로 남겼다.
한국 OSS 관행 실측¶
결정 근거로 삼기 위해 비슷한 프로젝트의 실제 상태를 측정했다. gh API 로 README ·
이슈 제목 · 이슈 본문 · PR 제목 · PR 본문 · 커밋 메시지를 각각 최근 40건 가져와
한글 문자 비율(%) 을 계산한 값이다. 관측일 2026-09-27.
| 저장소 | README | 이슈 제목 | 이슈 본문 | PR 제목 | PR 본문 | 커밋 |
|---|---|---|---|---|---|---|
| 한국 도메인 + 한국 사용자 | ||||||
| PublicDataReader | 27 | 66 | 47 | 28 | 5 | 9 |
| pykrx | 47 | 30 | 20 | 9 | 12 | 1 |
| FinanceDataReader | 23 | 50 | 25 | 9 | 24 | 1 |
| 한국 도메인 + 해외 사용자 | ||||||
| kiwipiepy | 31 | 43 | 32 | 24 | 19 | 1 |
| soynlp | 44 | 19 | 25 | 23 | 22 | 1 |
| konlpy | 3 | 18 | 12 | 1 | 0 | 1 |
| 한국 출신 + 글로벌 범용 | ||||||
| es-toolkit / billboard.js / pinpoint | 0 | 0 | 0 | 0 | 0 | 0 |
| 국내 전용(교육) | ||||||
| woowacourse/service-apply | 18 | 96 | 45 | 1 | 65 | 0 |
데이터에서 읽은 것¶
커밋 메시지는 예외가 없다. 한국 도메인 프로젝트 전부 1~9% 다. 그 잔여분도 대개 의존성 이름이나 인용이다. 관행이라기보다 사실상 규칙이다.
PR 제목이 이슈 제목보다 일관되게 낮다. PublicDataReader 66→28, service-apply 96→1. 아무도 문서화하지 않았는데 같은 방향으로 갈렸다 — squash merge 가 PR 제목을 커밋 메시지로 만들기 때문이다. 이 구분은 우리가 발명한 것이 아니다.
README 는 가장 넓게 퍼진다(3~47%). 해외 사용자가 생기면 내려가지만 자동은 아니다 — kiwipiepy 31%, soynlp 44% 는 해외 사용자가 있는 상태에서도 한국어가 높다. konlpy 3% 는 학술 인용을 목적으로 영어를 택한 예외에 가깝다.
언어 정책을 명문화한 곳은 10곳 중 1곳뿐이다. toss/es-toolkit 만
CONTRIBUTING.md 에 적어 두었고, 나머지는 CONTRIBUTING 이 있어도 언어를 언급하지
않거나 CONTRIBUTING 자체가 없다. 즉 이 관행은 대부분 암묵적으로 유지된다.
결정¶
| 영역 | 언어 |
|---|---|
| 코드 식별자, 주석, docstring | 영어 |
Governance 문서 (AGENTS.md, CONTRIBUTING.md) |
영어 |
구현 규약 문서 (PROVIDER_ADAPTER_CONTRACT.md, API_SPEC.md) |
영어 |
설계 판단 문서 (VALIDATION.md, ARCHITECTURE.md, ADR) |
한국어 |
| 커밋 메시지 | 영어 |
| PR 제목 | 영어 (Conventional Commits) |
| CHANGELOG · 릴리스 노트 | 영어 |
| README | README.md 한국어 · README.en.md 영어 (2026-09-27 개정) |
| 이슈 제목 | 영어 |
| 이슈 본문 | 한국어 또는 영어 |
| PR 본문, 리뷰 코멘트 | 한국어 또는 영어 |
한국 도메인 문서 (docs/providers/, 공공누리·활용신청 절차) |
한국어 유지 |
| 사용자에게 보이는 문자열 리터럴 | 이 정책의 대상이 아니다 |
경계가 왜 여기인가¶
제목은 영어, 본문은 자유. 경계가 제목과 본문 사이에 있다.
제목은 목록·검색·릴리스 노트·교차 참조에 나타난다. 이슈 목록을 훑는 사람은 제목만
읽고, PR 제목은 squash merge 로 커밋이 되어 CHANGELOG 로 이어진다. docstring 은
help() 와 API 문서로 나간다. 전부 밖으로 나가거나 오래 남는다.
본문은 논의다.
규약과 판단을 가른다 — 2026-09-28 추가¶
#500 이 VALIDATION.md 와 PROVIDER_ADAPTER_CONTRACT.md 의 언어 혼용을 지적했다.
두 문서를 같은 칸에 넣을 수 없어서 기준을 하나 더 만든다.
읽는 사람이 무엇을 하려고 읽는가로 가른다.
| 읽는 목적 | 언어 | |
|---|---|---|
PROVIDER_ADAPTER_CONTRACT.md · API_SPEC.md |
구현한다 — 이대로 코드를 쓴다 | 영어 |
VALIDATION.md · ARCHITECTURE.md · ADR |
판단한다 — 왜 이렇게 됐는지 읽는다 | 한국어 |
규약 문서는 AGENTS.md 와 같은 부류다. 코드를 고치려는 사람이 읽고, 그 사람은 코드가
영어인 것과 같은 이유로 영어를 읽는다. 시그니처·타입·필드명이 본문의 절반이라 번역할
수 있는 것도 아니다.
판단 문서는 다르다. 지금 이 프로젝트에서 그 판단을 내리고 검토하는 사람이 한국인이고, 근거를 정확히 쓰는 것이 읽는 사람 수를 넓히는 것보다 중요하다. 그리고 근거에는 활용신청·공공누리처럼 한국어로 써야 정확한 것이 자주 나온다.
PROVIDER_ADAPTER_CONTRACT.md 의 한국어 튜토리얼 절(3~5절)은 그대로 둔다 — 그것은
규약이 아니라 입문 설명이고, #546 이 정한 대로 참조 문서로 옮기는 것이 맞다.
README 를 두 파일로 나눈 이유 — 2026-09-27 개정¶
이 ADR 은 처음 README.en.md 를 기각했다. 사유는 이렇게 적혀 있었다.
별도 파일(
README.en.md)이 아니라 같은 파일의 뒤쪽 절로 둔다. 번역을 별도 파일로 두면 유지되지 않는다.
그 걱정은 사실이고 없어지지 않았다. 방향을 바꾼 것은 한 파일 방식이 다른 방식으로 실패하고 있었기 때문이다 — 영어 절이 553줄 README 의 490행부터 시작했다. 영어권 독자가 그 줄까지 내려갈 이유가 없으므로, 유지는 됐지만 읽히지 않았다.
그래서 사유를 문서로 반박하지 않고 장치로 무력화한다.
scripts/check_readme_parity.py 가 두 파일의 ## 절 개수·순서를 대조하고, 한쪽에만
절이 생기면 CI 가 실패한다. 내용 동일성은 검사하지 않는다 — 불가능하고 필요하지도
않다. 실제로 갈라지는 것은 한쪽에만 추가된 절이고 그것만 막으면 된다.
같은 검사가 150줄 상한도 강제한다. 553줄 85제목 상태에서는 절 대조가 유지될 수
없었다 — 구조 정리가 분리의 전제였다(#546).
Governance 문서는 왜 영어인가 — 2026-09-27 추가¶
이 표에 AGENTS.md 항목이 없었다. 그래서 세 저장소의 AGENTS.md 가 한국어로 남아
있었고, 거기 적힌 규칙이 "주석은 영어" 였다.
규칙을 영어로 지키라고 한국어로 적어 두면, 한국어를 모르는 기여자는 자기가 무엇을
어겼는지 읽을 수 없다. README 와 다르다 — README 는 프로젝트를 소개하고 한국인
사용자가 먼저 읽지만, AGENTS.md 는 코드를 고치려는 사람이 읽는 규칙이고 그
사람은 코드가 영어인 것과 같은 이유로 영어를 읽는다.
CONTRIBUTING.md 도 같다. 기여 절차를 읽을 수 없으면 기여할 수 없다.
POLICY.md 와 ADR 은 이 결정에 포함하지 않았다. 그것들은 오너와 triage 가 읽는
운영 문서이고, 기여자가 코드를 고치기 전에 반드시 읽어야 하는 것이 아니다. 필요해지면
따로 정한다.
README 는 왜 한국어가 먼저인가¶
현재 사용자와 기여자 대부분이 한국인이고, README 는 그들이 가장 먼저 읽는다. 영어를 앞에 두면 현재 독자 전부가 자기 언어를 두 번째로 읽게 된다 — 아직 오지 않은 독자를 위해 이미 있는 독자에게 비용을 지운다.
별도 파일(README.en.md)이 아니라 같은 파일의 뒤쪽 절로 둔다. 번역을 별도
파일로 분리하면 한쪽만 갱신되고, 유지되지 않는 번역은 몇 달 뒤 거짓이 된다 — 없는
것보다 나쁘다. 같은 파일에 인접해 있으면 한쪽만 고친 것이 diff 에서 보인다.
영어 절은 전문 번역이 아니라 판단에 필요한 최소치다 — 이것이 무엇이고, 무엇을 하지 않고, 어디서 시작하는지. 기여자와 핵심 사용자 대부분이 한국인이고, 도메인 논의는 한국어가 더 정확하다. 이슈 본문을 영어로 강제하면 참여 문턱만 올라가고 얻는 것이 없다.
문자열 리터럴은 별개다. 예외 메시지·로그·CLI 출력·UI 문자열의 언어는 런타임 동작이고, 사용자가 누구인지에 따라 정해진다. 코드 스타일 규칙으로 정할 일이 아니다.
운영 규칙¶
- 영어로 올라온 이슈에는 영어로 답한다. 해외 기여자가 한 명이라도 오면 이것이 가장 중요하다.
good first issue는 영어로 쓰거나 병기한다. 외부 기여를 받으려는 이슈가 한국어면 그 이슈는 외부 기여를 받지 못한다.- 이슈·PR 템플릿은 영어로 쓰고 한국어 안내를 괄호로 병기한다.
- ADR 과 주요 API 변경은 논의가 한국어여도 결론에 영어 요약을 남긴다.
- 한국어 문서의 문체는 해요체가 아닌 평서체로 통일한다. 여러 사람이 쓰면 문체가 갈리고, 갈린 문서는 번역본처럼 읽힌다.
- 영어로 쓰기 어렵다는 이유로 기여를 막지 않는다. 이슈나 PR 제목을 영어로 쓰기 어려우면 한국어로 올리고 그렇게 말해 달라 — 제목은 triage 나 리뷰에서 함께 정리한다. 이 문장이 없으면 "제목은 영어" 가 그대로 기여 장벽이 된다.
결과¶
지금 맞는 것¶
| 항목 | 현재 | 결정 |
|---|---|---|
| 커밋 메시지 | 1~4% | ✅ |
| PR 제목 | 0~1% (우리 PR) | ✅ |
| 이슈 | 혼용 | ✅ |
작업이 필요한 것¶
| 항목 | 현재 | 작업 |
|---|---|---|
| 코드 주석·docstring | 약 3,300건 한국어 | #517 진행 중 |
| README ×3 의 영어 절 | 없음 | 신규 작업 (한국어 본문은 그대로) |
README 는 각 400~500줄이고 한국어 본문은 손대지 않는다. 뒤쪽에 영어 절을 더하는 일이며, 전문 번역이 아니라 판단에 필요한 최소치다 — 무엇이고, 무엇을 하지 않고, 어디서 시작하는지. 대략 20~40줄.
하지 않을 것¶
- 이미 영어로 옮긴 이슈 42건을 한국어로 되돌리지 않는다. 영어 이슈도 이 정책에서 유효하고, 되돌리는 일은 내용을 개선하지 않으면서 이력만 늘린다.
docs/전체를 영어로 번역하지 않는다. 해외 기여자가 실제로 나타나기 전에 번역본 유지 비용을 먼저 지불하게 된다. 번역만 만들고 방치하면 6개월 뒤 거짓이 되고, 그건 없는 것보다 나쁘다.
대안과 기각 이유¶
전부 영어 (es-toolkit 방식). 도메인 논의의 정확성을 잃고 참여 문턱이 올라간다. 그 방식이 성립하는 이유는 es-toolkit 의 도메인이 한국과 무관하기 때문이다.
전부 한국어 (1군 방식). docstring 이 한국어면 help() 를 읽을 수 없고, 글로벌
공개라는 목표와 직접 충돌한다.
README 를 영어 기본으로. 처음 이 ADR 이 택했던 안이다. 기각한 이유는 현재 독자 전부가 한국인인데 그들에게 자기 언어를 두 번째로 읽게 만든다는 것이다. 실측 관행(23~47% 한국어)도 반대 방향이었다.
README 영어판을 별도 파일로. 유지되지 않는 번역은 거짓이 되고, 별도 파일은 한쪽만 갱신되기 쉽다. 같은 파일에 두면 drift 가 diff 에 드러난다.
이슈 제목을 한국어로 허용. 이쪽도 관행은 한국어다 — 실측 19~96%, service-apply 는 96% 다. 그럼에도 영어로 고정한 이유는 제목이 목록·검색·교차 참조에 나타나는 유일한 텍스트라는 것이다. 이슈 목록을 훑는 사람은 제목만 읽는다.
관행에서 벗어나는 지점은 하나다¶
이슈 제목뿐이다. 실측 19~96%, service-apply 는 96% 이므로 관행은 한국어를 가리킨다. 나머지 — 코드·커밋·CHANGELOG 영어, 본문 자유, README 한국어 우선, 한국 도메인 문서 한국어 — 는 전부 측정된 관행과 같은 방향이다.
이 문서의 첫 판은 README 도 영어로 두어 벗어나는 지점이 둘이었다. 하나로 줄었다.
대신 그 비용을 상쇄하는 장치를 둔다 — 본문은 한국어를 그대로 허용하고, 제목을 영어로 쓰기 어려우면 한국어로 올리고 말해 달라고 명시한다. 제목 하나 때문에 이슈를 안 올리는 일이 생기면 이 정책은 실패한 것이다.
참고¶
- 측정 스크립트와 원자료: 이 ADR 의 표가 전부다. 재현하려면
gh api로 위 항목을 가져와 한글 문자 비율을 계산하면 된다. - 관련: #517 (코드 주석 영어화), POLICY 언어 절, 세 저장소
AGENTS.md