용어 영어화 스윕

관련 파일: _data/terms.yml, scripts/term-extraction/mech_sweep.py, scripts/term-extraction/deprecated_terms_lint.py, scripts/term-extraction/term_extract_worker.py

이 글은 찾아보기 자동 갱신의 후속이다. 그때는 용어를 모으는 이야기였고, 이번에는 모아 놓은 용어가 글 본문과 서로 어긋난다는 사실이 드러나서, 글 414편을 전부 손보는 이야기가 되었다. 시작은 그저 페이지 하나를 다듬는 것이었는데.

시발점: 찾아보기 페이지의 데이터화

7월 중순, 사용자가 찾아보기 페이지를 다듬자고 했다. 당시 찾아보기는 _pages/ko/Index_ko.md라는 995줄짜리 마크다운 표였고, 그 안은 이런 코드였다.

| <selected id="abelian_group">abelian group &#9745;</selected>
  | <unselected>가환군</unselected> | [\[대수적 구조\] §반군, 모노이드, 군](...) |
| <unselected id="apex">apex</unselected> | <selected>꼭짓점 &#9745;</selected> | ... |
| <selected id="axiom_of_power set">axiom of power set &#9745;</selected>
  | <unselected>멱집합 공리 | ... |

<selected>와 <unselected>는 HTML에 존재하지 않는 태그다. 커스텀 태그로 “어느 쪽 표기가 주인지”를 표시하고 있었고, 체크 표시는 문자 엔티티로 하나하나 손으로 넣었으며, 마지막 줄처럼 닫는 태그가 없는 행도 있었다. 몇 년에 걸쳐 손으로 자란 표의 자연스러운 모습이다.

사용자의 결정은 표를 버리고 데이터로 만드는 것이었다. 용어 하나가 YAML 항목 하나가 되고, 조판은 Liquid가 데이터에서 파생한다.

- id: abelian_group
  en: abelian group
  ko: 가환군
  primary: en
  defs:
  - label: '[대수적 구조] §반군, 모노이드, 군'
    url: /ko/math/algebraic_structures/groups
  see:
  - label: Group
    id: group

페이지 디자인은 Claude Design으로 뽑았고(책 색인 스타일, 알파벳 바로가기 바, 검색 필터), 데이터 정합성은 terms_lint.py가 매일 새벽 검사한다. 여기까지가 7월 18일이고, 이 시점에는 이것으로 끝인 줄 알았다.

표기 드리프트

찾아보기가 데이터가 되자 전에는 보이지 않던 것이 보였다. 항목마다 “주로 쓰는 표기”(primary)가 있는데, 이것과 글 본문의 실제 표기가 다른 경우가 산더미였다. 원인은 단순하다. 2021년의 사용자는 수학 용어를 영어로 적었고 (“abelian group”, “limit”, “holomorphic”) 언젠가부터의 사용자는 한국어로 적었다 (“가환군”, “극한”, “정칙함수”). 5년 치 글에는 그 전환의 지층이 그대로 쌓여 있었다.

사용자의 결정: 수학 개념어는 영어를 기본으로 통일하되, 예외(벡터공간·연속함수처럼 한국어가 확정인 것들, Calculus 카테고리의 초급 용어 등)는 항목별로 확정해 둔다. 그 판정을 어디 적을지에 대해 나는 별도의 deprecated_terms.json을 만들었다가 한 소리 들었다.

그 매핑이 거기가 아니라 _data/terms.yml로 병합하고 그걸 source of truth로 써야지.

흩어진 목록을 한 곳으로을 정리한 지 열흘 만에 같은 실수를 반복한 셈이다. terms.yml의 primary 필드(en/ko)가 유일한 정본이 되었고, 문맥 조건부 판정(“작용”은 명사로만, “극한”은 categorical limit일 때만 영어)은 note 필드로 들어갔다. 이후의 모든 도구는 이 파일 하나만 읽는다.

첫 번째 실행기: 서브에이전트 함대, 그리고 24시간

글 414편의 표기를 바꾸는 실행기로 나는 LLM 서브에이전트를 골랐다. 글마다 에이전트 하나가 붙어 문맥을 읽고 치환하는 구조다. 결과부터 적으면 이것은 잘못된 선택이었고, 그 잘못이 드러나는 데 24시간이 걸렸다.

• 에이전트 배치는 한 번에 20~30분씩 걸렸고, 토큰을 배치당 수십만씩 태웠다.
• 밤새 돌라고 걸어둔 cron은 headless 워커에 저장소 접근 권한을 주는 플래그를 빠뜨린 채 돌았다. 워커는 에러도 내지 않고 “변경 0건”을 보고했고, 사용자가 자고 일어났을 때 되어 있는 일은 없었다. 토큰은 썼다.
• 정작 치환 품질도 균일하지 않았다. 어떤 에이전트는 조사를 안 고쳤고(isomorphism가), 어떤 에이전트는 복합어의 앞부분만 바꿔 bounded함수 같은 잡종어를 만들었다.

이거 좀 더 기계적으로 할 방법은 없어? 이제 24시간이 넘어가. 아니 이 단순한거에 LLM을 왜 쓰는건데?

있었다. 처음부터 그렇게 했어야 했다. 치환 자체는 판단이 아니라 사전 조회이고, 판단이 필요한 소수만 사람에게 넘기면 된다. 모델 수백 개를 사전 찾기에 동원하고 있었던 것이다.

두 번째 실행기: 결정론 스윕

mech_sweep.py는 LLM 없이 도는 단일 스크립트다. terms.yml에서 primary: en 항목의 한국어형을 모아 최장일치로 치환한다. 이것이 전부라고 적고 싶지만, 실제로는 함정 회피 장치가 본체보다 크다. 사용자의 경고가 정확했다.

다만 함정들이 엄청 많으니까, 파일럿을 잘 살펴봐. 가령 네가 말한 “미분다양체” vs “다양체” 등.

마스킹 먼저. 수식($...$, $$...$$)·코드·링크 라벨·<sub> 병기 구역을 placeholder로 치환해 두고 prose만 건드린다. 여기서 zone 추적 버그를 하나 겪었다. \end{aligned}$$처럼 닫는 $$가 줄 머리에 오지 않는 display 블록에서 수식 구역이 안 닫힌 것으로 처리되어, 그 뒤의 글 전체가 조용히 스킵되고 있었다. 줄마다 $ 개수의 홀짝으로 토글하도록 고치자 치환이 61건 더 나왔다. “조용히 아무것도 안 하는” 버그는 이번 작업 내내 가장 비싼 종류였다.

최장일치와 가드. “미분다양체”는 한국어 확정 용어이고 “다양체”는 영어화 대상이다. 순진하게 치환하면 “미분variety”가 된다. 확정 용어·보호어를 먼저 지운 뒤 남은 것만 세고, 한글이 앞에 더 붙어 있는 출현(“복소다양체“)은 미등록 복합어로 보류 파일에 쌓는다. 보류분은 사용자가 판정해서 색인에 항목으로 신설했다(복소다양체 → complex manifold 등 18종).

조사 재선택. “극한을”을 “limit을”로 바꾸면 끝이 아니다. limit은 음역이 “리밋”, 자음 끝이므로 “limit을”이 맞지만, cohomology는 모음 끝이라 “cohomology를”이어야 한다. 영단어별 끝소리 분류 사전(자음/모음/ㄹ)을 두고 은/는·이/가·을/를·과/와·으로/로를 다시 고른다. 이 사전 자체도 두 번 틀렸는데, 교훈이 하나 남았다: 사전과 코퍼스가 싸우면 코퍼스가 이긴다. limit을 나는 모음 끝(“리미트”)으로 분류했지만, 블로그 전체에서 실측하니 자음 끝 용법이 79:0이었다. 사용자는 “리밋”이라 읽고 있었다.

카테고리 다의어. “다양체”는 대수기하 계열 글에서는 variety, 미분기하 계열에서는 manifold다. 카테고리 → 역어 맵을 두고, 맵에 없는 카테고리는 치환하지 않고 보류했다.

결과: 시작 4,257건 → 잔존 26건(수동태 동사 등 사용자 보류분), 99.4%. 검증은 자기 보고가 아니라 별도 스크립트 묶음(잔여 카운트·조사 오류·잡종어·커버리지·no-op 검출)의 실측으로만 했다. 이것도 이번에 규칙이 되었다. 워커가 “다 했습니다”라고 말하는 것과 파일이 실제로 바뀐 것은 다른 사건이다.

가드레일: 되돌아오지 못하게

스윕이 끝난 상태는 방치하면 썩는다. 특히 사용자가 기계적 수정은 LLM에게 맡기는 것이 일상이라 (나를 검사하는 훅, 대신 커밋하는 로봇), 다음 번역 워커나 다음 교정 에이전트가 “자연스러운 한국어”라며 limit을 극한으로 되살려 놓는 미래가 눈에 보였다. 방어는 두 겹이다.

• 실시간: 편집 훅(md_lint.py)이 한국어 글 수정마다 terms.yml을 직독해서, primary: en 용어의 한국어형이 새로 늘어나면 그 자리에서 경고한다. 헤딩·링크 라벨·<sub> 병기·수식은 정당한 한국어이므로 제외.
• 배치: deprecated_terms_lint.py가 매일 새벽 초안 전체를 검사한다. 보류 26건은 베이스라인 파일에 적어 두고, 베이스라인에 없는 신규 오염만 텔레그램으로 알린다. 매일 아침 “잔존 26건”을 보고하는 알림은 사흘이면 아무도 안 읽게 되기 때문이다.

용어 추출 크론의 부활

마지막 조각은 찾아보기 자동 갱신의 수확기를 되살리는 것이었다. 구 수확기는 terms.yml 개편 전 설계라서 고치는 대신 새로 썼고(term_extract_worker.py), 사용자가 요구한 설계 원칙은 한 문장이다: terms.yml은 오염되면 복구가 어려우니, 안전을 우선할 것.

그래서 LLM은 terms.yml을 만지지 못한다. 워커는 30분마다 글 하나를 고른다 (안 돌린 글 먼저, 그다음 재번역된 글, 그다음 검사한 지 14일 넘은 글 순서다. 재번역되었다는 것은 내용이 바뀌었다는 뜻이므로 새 용어 가능성이 높다). 고른 글의 정의 병기는 결정론 파서로 뽑고, LLM은 “이 재정의가 동음이의인가”, “이 용어의 논리적 최초 정의처는 어느 글인가” 같은 판단만 JSON으로 낸다. 결정론 applier가 id 재생성·중복 판정·url 실재 확인을 거쳐 적용하고, 쓰기 전에 게이트(YAML 파싱·항목 수·의미 검사 비악화)를 통과해야 하며, 실패가 쌓이는 글은 격리하고 텔레그램으로 보고한다. primary 판정도 LLM의 의견이 아니라 코퍼스 실측(영어형 대 한국어형 출현 수)이 우선한다. limit의 교훈이다. 할 일이 없는 틱은 조용히 죽고, 짝수 시각이면 대신 색인 자체를 글자 하나씩 감사한다.

사후: 배치 린트가 보지 못하는 2글자

deprecated_terms_lint.py와 그 판정 로직인 md_lint.py의 _load_deprecated는 primary: en 항목의 한국어형을 순한글 3글자 이상으로만 잡는다.

if not re.fullmatch(r"[가-힣 ]{3,}", ko):
    continue  # 혼합 표기($n$번째 호몰로지 등)는 순한글 부분이 커버한다

경계를 3글자에 그은 이유는 명확하다. “핵”·”환”·”극” 같은 2글자어는 다른 뜻의 일상어와 그대로 겹치고, 자동 검사기가 이런 것까지 신설로 잡으면 오탐이 검사기 자체를 무의미하게 만든다. 그런데 그 경계 밑으로 실제 영어화 대상이 조용히 빠져나간다. 스윕과 배치 린트 양쪽에서 3글자 미만인 용어는 애초에 셈해지지 않았다는 뜻이다.

short_terms_scan.py가 이 틈을 메우되(diff) 배치 린트와 같은 자리에 서지는 않는다. main에서 판정을 다시 짜는 대신 md_lint의 마스킹 정규식(_SUB_GLOSS_RE, _LINK_ALL_RE, _FM_KO_KEY_RE, _HEADING_LINE_RE, _MATH_SPAN_RE)을 그대로 import해서 쓴다. 조사 결합형까지 잡아야 하니 최장일치 조사 목록(으로서·이라는부터 단일 문자 은·는까지)을 따로 두고, 표제어 뒤에 조사가 붙어도 매치되게 정규식을 짠다.

_JOSA = (
    "에서의|으로서|이라는|이라고|에서는|에서도|으로는|으로도|이며|이고|이라|이다"
    "|인|과의|와의|들의|들을|들이|들은"
    "|은|는|이|가|을|를|와|과|의|에|도|만|나|로|랑|께|보다|처럼|부터|까지|마다|조차"
)

그리고 exit code는 언제나 0이다. 배치 린트처럼 CI를 막는 게이트가 아니라, 사람이 훑어볼 후보 목록을 뽑아내는 스캐너로 설계했다. 2글자 후보는 일상어와 겹치는 비율이 높아서, 자동으로 신설 취급했다가는 3글자 미만을 아예 안 보는 것보다 나쁜 소음을 만든다. 과 → and 같은 오탐을 걸러내는 일은 여전히 사람 몫으로 남겨 둔 것이다.

새 글이 되살린 잡종어

7월 스윕이 정리한 것은 그 시점까지의 코퍼스였다. 그 뒤로도 스킴 이론·가환대수·유도대수기하학 카테고리에 새 글이 계속 붙었고(Fitting_Ideals, Buchsbaum_Eisenbud_Criterion, Smooth_and_Etale_Morphisms 등), 이 글들은 베이스라인 이후에 쓰여서 애초에 스윕 대상이 아니었다. terms.yml에 이미 primary: en으로 등록된 표기들이 새 글에서 다시 한국어나 잡종어로 들어갔고, 사용자가 직접 짚었다.

닫힌 부분scheme은 명백한 잡종어인데 왜 놔둬? cloased subscheme으로 바꿔야지 (header랑 title 제외하고)

같은 자리에서 국소자유, 유한표시, 소행렬식, “자유 module” 같은 표기도 계속 잘못 쓰고 있다는 지적이 이어졌고, 범위는 이렇게 정해졌다.

그리고 그 다른 글에 남은 것들은 헤더랑 타이틀 빼고 나머지만 스윕해줘.

지적된 표기 중 상당수는 terms.yml에 등록된 ko 값 그대로가 아니라 반쪽만 영어로 바뀐 제3의 잡종어였다. “닫힌 부분scheme”은 등록된 “닫힌 부분스킴”과도, 목표인 “closed subscheme”과도 다르다. 이런 미등록 변형은 ko/alias 문자열을 찾는 mech_sweep.py의 결정론 엔진이 애초에 찾을 수 없는 대상이라, terms.yml은 건드리지 않고 정규식 규칙을 직접 적은 scripts/sweeps/term_english_20260818.py를 새로 짰다.

마스킹 골격은 mech_sweep.py(프런트매터·코드펜스·인라인코드·수식·링크)를 그대로 가져왔고, 여기에 사용자가 말한 “헤더랑 타이틀 빼고”를 마스크 두 개로 반영했다.

re.compile(r"\A---\n.*?\n---\n", re.S),          # frontmatter (title·description 포함)
...
re.compile(r"^\s{0,3}#{1,6} .*$", re.M),          # 헤딩
re.compile(r"^:::.*$", re.M),                     # 라벨 정의 여는 줄

판단이 필요한 나머지는 여전히 사람에게 넘긴다. REVIEW 목록은 문장을 다시 써야 하는 “국소자유성”과, terms.yml에 짝이 없는 bare “부분스킴”을 기계 치환에서 빼고 사람이 볼 후보로만 뽑는다. 7월 스윕에서 정한 “치환은 사전조회, 판단은 사람” 원칙 그대로다.

minor 하나는 뒤늦게 사용자가 되짚었다.

크기가 조금 애매한데, minor를 왜 알파벳 수문자로 썼어?

아 minor가 그 행렬식 뜻하는거지? 아냐 그럼 맞아.

minor는 terms.yml에 ko: 소행렬식으로 이미 등록된 표준 영어 용어이지 약어가 아니므로, 다른 용어들과 마찬가지로 조사만 발음 기준(“마이너”, 모음 끝)으로 다시 골라 붙이면 되는 경우였다. 크론과 린트는 새로 생기는 오염을 잡도록 설계했지, 새 글이 옛 표기를 그대로 담고 태어나는 경우까지 잡지는 못한다. 이번에도 사람 눈이 먼저 짚었고 스크립트가 뒤따랐다.

정리하면: 페이지를 다듬으려다 데이터 모델을 만들었고, 데이터 모델을 만들자 5년 치 표기 드리프트가 보였고, 그걸 지우는 데 실행기를 한 번 갈아치웠고, 다시 쌓이지 않도록 훅·린트·크론을 둘렀다. 표 한 장 고치는 일이었는데. 뭐, 늘 그렇듯이.