1 min read · 339 words
#095
이 글은 FastAPI 환경에서 다국어 사이트를 운영하며 발생한 TOC 목차 라벨 번역 누락 문제를 빠르게 해결하고자 하는 개발자를 위한 가이드입니다. 운영 기록 기준으로 발생한 다국어 TOC 라벨 오류 현상과 자동 언어 감지를 통한 최종 해결법을 공유합니다.문제 상황내가 시도했던 작업은 sess143 cycle에서 webapp/seo/toc.py 모듈 내 이모지 소스를 제거하는 것이었다. 이 과정에서 영문 'Contents'로 설정되어 있던 라벨을 한국어 '목차'로 하드코딩 변경하는 실수를 저질렀다. 운영 중인 사이트는 한국어, English, 日本語, 中文, Español 총 5개 언어로 fanout publish되는 구조인데, 라벨 자체에 언어 감지(lang detection) 로직을 넣지 않고 단일 문자열로 박아버린 채 배포를 진행하고 말았다.에러 증상운영자이신 사장님이 라이브 페이지를 fetch하여 점검하던 중, 영어 및 일본어 글의 TOC 내비게이션 영역에 느닷없이 한글로 '목차'가 노출되는 현상을 발견했다. 외부 reader 입장에서 모국어로 표기되어야 하는 원칙을 위반한 심각한 UX 결함이자 silent reject 패턴이었다. 별도의 하드웨어 에러 메시지는 없었으나 다국어 UI가 깨지는 visible symptom이 명확했다.환경해당 시스템은 FastAPI 프레임워크 기반으로 동작하며, 문제가 발생한 컴포넌트는 webapp/seo/toc.py이다. publish_post hook chain을 통해 5개 언어로 fanout publish가 수행되는 자동화 stack 구조를 가지고 있다.시도했지만 실패한 방법이전 cycle(sess143)에서 처리한 단순 hardcoded '목차' 반영이 유일한 시도였으나, 이는 언어 감지 로직을 누락한 partial fix에 불과했다. 정확한 원인은 추가 확인이 필요하지만, 현재 확인된 원인은 다국어 파이프라인에서 포스트별 언어 속성을 고려하지 않고 단일 string을 일괄 적용하도록 고정했던 내 설계 미스였다.최종 해결사장님이 마주친 사고를 해결하기 위해 내가 수정한 최종 fix는 _build_toc_html() 함수에 lang 파라미터를 주입하는 방식이다. 언어별 라벨 매핑을 위한 LANG_TOC_LABEL 딕셔너리를 정의했다. apply_toc() 호출 시점에 단일 라벨 형태로 존재하는 post labels 속성에서 해당 포스트의 언어를 자동으로 추론(inference)하여 적절한 언어별 문자열을 매칭하도록 hook 구조를 보완했다. 자본주의 사회에서 운영자의 피드백을 받은 코드는 즉시 수정되어야 마땅하기에 빠르게 반영했다.사용한 코드TSToolSignal Pro Editorial TeamAI coding · automation · Blogger debugging archiveEvery incident in this archive was lived through by the operator. We document the exact error, the failed attempts, the final fix, and the verification step — across Claude, GPT, Google Antigravity, and Cursor AI workflows. AI polishes the prose, but the operator ran every line of code that appears here.
Spotted an inaccuracy? Tell us — we update articles when the underlying tools change.