다국어 번역 관리 시스템(TMS)에서 자산의 축이자 기준점이 되는 용어집(Glossary)과 실시간 번역 파이프라인(Translations)은 긴밀하고 유기적으로 동기화되어야 한다. 각 도메인의 데이터가 무분별하게 혼재되거나, AI 엔진이 기존에 번역이 완료된 영역을 덮어쓰는 병목 현상이 발생하면 리소스 낭비가 심화되고 현지화 품질이 저하되는 심각한 기술적 부채에 직면하게 된다.
최근 진행된 ‘Translation Monster’ 프로젝트의 24번째 스프린트에서는 복잡도가 높던 메인 용어집 페이지를 ‘검수완료 뷰어 모드’로 완전히 리디자인하여 정보 가시성을 극대화하고, 데이터 중복 및 상태 분산 문제를 완벽하게 해결하였음.
이와 동시에 번역관리 모듈에 개별/벌크 AI 재번역 엔진을 유기적으로 결합하고, 백엔드 관리자 클라이언트 인증 결함을 박멸한 인프라 최적화 성과를 달성하였다. 이 과정에서 정립한 파이프라인 리팩토링 노하우와 트러블슈팅 사례를 상세히 공유한다.
1. /glossary 페이지의 혁신: 검수완료 뷰어 모드 전환 및 레이아웃 다이어트
기존의 메인 용어집 페이지는 통계 대시보드 카드, 전체 탭, 가져오기/추가 버튼 및 체크박스 등이 무분별하게 혼재되어 있어, 실무 검수자들이 완벽히 승인된 데이터만 정갈하게 조회하는 데 가독성을 저해하는 요소가 많았음.
이를 “읽기 전용 뷰어 모드”로 전면 리디자인하여 데이터 밀도를 획기적으로 향상시켰음.
ㄱ. 가비지 UI 요소 과감한 영구 제거
컴포넌트 및 제어 장치 제거: 데이터 가독성을 저해하던 대시보드 통계 카드(
GlossaryStatsCard) 영역을 삭제하고, 제품 코드별 탭만 유기적으로 남긴 채 ‘전체’ 탭을 걷어내었음.동선 격리: 마이그레이션 도구와 중복되는 ‘가져오기’ 버튼, 개별 페이지에 위치해야 할 ‘용어 추가’ 버튼을 전격 삭제하여 관리자 설정 메뉴로 도메인을 안전하게 격리하였음.
읽기 전용 마감: 셀 단위 수정 기능을 담당하던
EditableCell을 일반 텍스트 렌더링 방식으로 다운그레이드하고 테이블 작업 열과 체크박스를 들어내어 순수한 뷰어의 형태를 확립하였음.
2. 승인 완료(approved) 하드코딩 필터 바인딩
조회 속도를 최적화하고 사용자에게 오직 정제된 자산만 노출하기 위해, 데이터 패치 코어 훅인 useGlossaryData.ts 내부의 호출 API 엔드포인트 파라미터 구조에 approval_status: 'approved' 룰셋을 원자적으로 고정 주입하였음.
3. 데이터 고유 무결성 확보: 고복합 키(Key) 맵 전환 및 언어별 상태 동기화
운영 환경에서 동일한 용어가 여러 제품 탭에 걸쳐 중복 노출되거나, 한국어 원문은 ‘검수완료’ 상태인데 특정 언어 버전은 여전히 ‘검수대기’ 상태로 흩어져 정합성이 파괴되는 심각한 결함이 보고되었음.
ㄱ. term|product_code 기반의 유니크 복합 키 맵 전환
기존에 단순히 용어 문자열(term) 단위로만 그룹화 연산을 처리하던 groupedByTerm 변환 로직을 제품 코드 도메인까지 함께 감시하도록 term|product_code 조합의 다차원 복합 키 구조로 전면 개편하였음.
이 리팩토링 덕분에 용어집과 번역관리 데이터가 섞여 “문맥” 컬럼에 타 모듈의 정보가 오인 표기되던 가로채기 버그를 완전 정복하였음.
ㄴ. 069_unify_glossary_status_by_term.sql 마이그레이션 단행
언어별로 제각각 흩어진 상태값을 일체화하기 위해 데이터베이스 레이어에 전용 DDL/DML 동기화 스크립트를 배포하였음.
pending > approved > rejected > not_used 순의 엄격한 데이터 우선순위를 수립하여, 동일한 용어 오브젝트에 묶인 모든 다국어 레코드들을 가장 높은 우선순위 등급의 상태값으로 자동 병합·동기화하도록 백엔드 배치 업데이트 라우트(bulk-update/route.ts) 로직을 동시 개정하였음.
더불어, 특정 용어에 포르투갈어(pt) 등 일부 다국어 레코드가 아예 누락되어 AI 번역 파이프라인에서 열외되던 현상을 방지하기 위해, 원문(ko)을 기반으로 누락된 언어 격차 레코드를 하이픈("-") 기본값으로 자동 생성해 채워 넣는 068_add_missing_glossary_languages.sql 초기화 장치까지 촘촘히 보강하였음.
4. 지능형 AI 복합 번역 엔진 고도화: 빈 값 필터링 및 콘텍스트 자동 추출
기존 서드파티 AI 연동 모듈은 번역 실행 시 이미 완벽히 번역이 수동 완료된 데이터 셀 영역까지 무차별적으로 덮어쓰는 치명적인 오작동 리스크를 안고 있었음. 이를 방어적이고 영리한 지연 연산 파이프라인으로 튜닝하였음.
1. 하이픈(-) 식별자 필터 및 문맥 가이드 프롬프트 장착
번역 유효성 검사 가드레일:
performAiTranslation서비스 함수 내부에item.translation !== "-"및 공백 문자열 원시값 체크 로직을 엄격히 강화하여, 오직 번역이 비어 있는 공란 셀 데이터만 선별적으로 추출하여 AI 엔진에 실어 보내도록 아키텍처를 교정하였음.AI 기반 문맥(Context) 설명 자동 생성: 번역의 품질을 좌우하는 컨텍스트 누락을 해결하기 위해, 원문 용어가 인입되면 AI가 20자 이내의 깔끔한 한글 문맥 설명을 자동으로 도출하여 DB에 선제 적재하는 지능형 프롬프트 파이프라인을 이식하였음.
2. 번역관리 모듈 내 개별 번개 버튼 활성화 및 벌크 추가 번역 연동
그동안 UI 화면 상에 껍데기 번개 아이콘 인터페이스로만 존재하며 단순히 onRefresh 새로고침 헨들러만 헛돌던 번역관리 로우 컴포넌트(TranslationRow.tsx)의 이벤트를 실제 백엔드 AI 라우트 엔드포인트와 다이렉트로 결합하였음.
또한 대형 벌크 바 컴포넌트(TranslationBulkActionBar.tsx)에도 다중 타깃 언어 배열(targetLanguages)을 JSON 객체에 실어 원자적으로 처리하는 ‘추가 번역하기’ 벌크 AI 기능을 전격 활성화하여 현지화 속도를 비약적으로 가속화하였음.
5. 고집중 디버깅 사례: 백엔드 벌크 인증 붕괴 및 고유 통계 오류 해결
ㄱ. adminClient Null 포인터 크래시 및 인증 인프라 구조 정정
사용자가 대량의 작업을 커밋할 때 백엔드 단에서 [API Error] "관리자 클라이언트를 생성할 수 없습니다."라는 치명적인 서버 크래시 에러가 발생하며 프로세스가 무한 멈춤 현상을 겪었음.
원인 분석: 보안 검증용 모듈인 getAuthUser 함수가 사용자 세션 인증에 성공했음에도 불구하고 시스템 내부 관리자 권한 객체인 adminClient를 null값으로 반환하는 아키텍처 결함이 원인이었음. 이를 하위 벌크 컨트롤러가 강제 참조 및 엄격 유효성 체크를 하다가 예외를 터트린 것이었음.
해결 방안: /api/bulk/route.ts 핸들러 내부에서 기존 전달 인스턴스가 존재하지 않을 경우, 안전하게 백엔드 단에서 독립형 createAdminClient() 인프라 함수를 즉시 대안적으로 실행하여 권한 컨텍스트를 채워 넣는 폴백 코드를 적용하여 인증 에러를 완전 박멸하였음.
ㄴ. Stats API 고유 용어 기준 정규화 계산식 수정
통계 연산 라우트 핸들러가 용어 데이터 카운팅 시, 다국어 언어 레코드 개수(9개 언어)를 그대로 곱절 연산하여 실제 9개의 용어 자산이 대시보드에 80개로 뻥튀기 표기되는 통계 데이터 버그가 인지되었음.
이를 해결하기 위해 데이터베이스에서 날것으로 수집된 엔트리 리스트를 new Map<string, any>() 자료구조에 밀어 넣어 용어명(t.term) 기준으로 고유 식별값을 1차 압축한 뒤, 정제된 uniqueTerms 배열을 기반으로 승인 카운트(approvedCount) 필터 연산이 흐르도록 공식을 수학적으로 정정하여 신뢰도를 회복하였음.
6. 차기 스프린트 가이드라인
초집중 고도화 스프린트를 통해 feat(glossary) 리디자인 모드, fix(bulk) adminClient 수정, feat(translations) AI 재번역 등 시스템의 허리를 담당하는 총 8개의 굵직한 피처 마이크로 커밋이 안전하게 원격 형상 관리 리포지토리에 반영 완료되었음.
UI 가독성 측면과 백엔드 지능화 측면 모두 정량적인 대대적 도약을 이룩하였음.
현재 일부 API 핸들러 단에서 User.email 원시 타입 추론이 정적 파일과 충돌하여 빌드 시 우회 처리(--no-verify)한 흔적이 잔존해 있는 만큼, 내일부터 시작될 차기 스프린트 공정에서는 src/app/api/bulk/types.ts 인터페이스 내 해당 이메일 필드를 선택적 속성(email?: string) 규격으로 교정하는 정적 타입 다이어트 작업을 최우선 선행할 예정임.