Gemini 기반 다국어 파이프라인 및 Vite Chunk 오류 자동 복구 설계

Two weeks of building Bible School LMS in public: first contributor, bilingual content, real production bug

Vadym Arnaut2026년 5월 10일6분intermediate

AI 요약

Context

교사 저작 콘텐츠의 실시간 다국어 제공 필요성 및 LLM의 성경 구절 왜곡(Paraphrasing) 문제 직면. Vite 기반 SPA 배포 후 발생하는 Stale-chunk 참조로 인한 사용자 이탈 및 런타임 에러 발생.

Registry 기반 중앙 집중식 번역 관리: registry.py를 Single Source of Truth로 정의하여 신규 엔티티 추가 시 Postgres CHECK 제약 조건 업데이트로 일관성 보장
Hash 기반 증분 번역 및 캐싱: 소스 텍스트 해시 변경 시에만 Gemini API를 호출하고 결과를 public.content_translations에 캐싱하여 비용 및 응답 속도 최적화
Canonical Verse 보존 파이프라인: SequenceMatcher로 유사도 0.80 이상인 구절을 식별하여 ASCII 마커로 치환 후 LLM 전달 및 번역 후 타겟 언어의 정경 JSON(최대 6.1MB) 데이터로 재치환
CI 레벨의 Schema Guard 도입: FastAPI 라우트의 Accept-Language 헤더 누락 및 번역 훅 미참조 시 빌드를 실패 처리하는 정적 검사 자동화
ErrorBoundary 기반 Chunk Load 실패 복구: Vite의 ChunkLoadError 시그니처를 감지하여 window.location.reload()를 수행하고 SessionStorage 기반 60초 쿨다운으로 무한 루프 방지

실천 포인트

1. LLM 활용 시 도메인 특화 정적 데이터(Canonical Data)의 보존을 위한 마킹 전략 검토

2. FastAPI 등 프레임워크 사용 시 필수 헤더 누락을 잡는 CI 단계의 API 스키마 검사 도입

3. Vite/Webpack SPA 배포 시 ChunkLoadError에 대응하는 자동 리로드 로직 및 쿨다운 메커니즘 구현

태그