영어만 한국어로 바꾸면 망가진다: 기존 ID를 지킨 Iloura 대시보드 UX 마이그레이션
영어만 한국어로 바꾸면, 대시보드는 더 쉽게 망가진다
대시보드의 메뉴와 데이터베이스 이름을 한국어로 바꾸는 일은 겉보기엔 번역 작업이다. 하지만 실제로 버튼 하나, 프로퍼티 하나를 바꾸는 순간 화면 뒤의 필터와 관계형 데이터까지 깨질 수 있다. 내가 Iloura Notion 대시보드를 한국어 UX로 옮기며 배운 결론은 단순했다. 마이그레이션의 대상은 문장이 아니라 계약이다.
처음부터 새 대시보드를 만들면 더 깔끔해 보인다. 새 데이터베이스를 만들고, 이름을 한국어로 짓고, 예시 행을 다시 넣으면 된다. 그런데 그 순간 기존 페이지가 참조하던 ID, 뷰의 필터, 연결된 관계, 이미 쌓인 행의 위치가 한꺼번에 불확실해진다. 화면은 새것이지만 운영 데이터는 낡은 곳에 남는, 가장 찾기 어려운 종류의 실패다.
이번 작업에서 나는 새 구조를 만들지 않았다. 기존 Iloura Notion 대시보드 ID를 그대로 둔 채, 사용자에게 보이는 층만 한국어 중심으로 바꿨다. 이 글은 그 과정에서 어떤 경계를 지켜야 같은 실수를 반복하지 않는지 기록한 BUILD LOG다.
[상호작용] 번역 전에 먼저 지킨 것은 화면이 아니라 ID였다
여기서부터의 근거는 외부 기사나 트렌드 데이터가 아니다. 2026년 9월 18일 에이전트와 내가 실제로 나눈 작업, 검증 결과, 그리고 그 결과를 메모로 남긴 상호작용에서 가져왔다.
첫 번째 결정은 in-place migration이었다. 기존 데이터베이스를 삭제하거나 새로 만들지 않고, 현재 대시보드가 가진 ID를 기준점으로 삼았다. 그 위에서 데이터베이스 제목, 프로퍼티 이름, select 옵션, 시드 행 제목을 한국어 우선으로 정리했다. 반대로 코드와 내부에서 쓰는 canonical key는 그대로 유지했다.
| 사용자에게 보이는 층 | 내부 계약 층 | 이번 마이그레이션의 원칙 |
|---|---|---|
| 데이터베이스 제목 | 기존 데이터베이스 ID | 제목은 한국어로, ID는 유지 |
| 프로퍼티·select 옵션 | 필터·스키마가 기대하는 키 | 라벨은 번역하되 canonical key는 안정적으로 보존 |
| 시드 행 제목 | 기존 행·관계·뷰 | 행은 이관하되 연결 상태를 검증 |
이 구분이 중요한 이유는 한국어가 더 친절해서가 아니다. owner_review 같은 내부 값까지 사람이 읽는 라벨처럼 바꿔버리면, 화면은 자연스러워져도 기존 필터가 더 이상 같은 값을 찾지 못한다. 번역은 프레젠테이션의 문제이고, 키는 시스템 계약의 문제다. 둘을 같은 문자열로 취급하면 나중에 원인을 추적하기 어렵다.
데이터를 옮겼다는 말과, 데이터가 같은 구조에 있다는 말은 다르다
두 번째로 신경 쓴 것은 “몇 개 복사했는가”보다 “비어 있어야 하는 곳이 정말 비어 있는가”였다. 이번 검증에서 시드 카운트는 5/3/0/3으로 확인됐다. 그리고 Schedule은 의도적으로 0행을 유지했다. 일정 데이터가 없는데 예시 행을 넣어 화면을 채우면 데모는 풍성해 보이지만, 운영자는 존재하지 않는 일정을 실제 일정으로 오해할 수 있다.
그래서 Schedule에는 schedule_zero_row_invariant=true라는 불변 조건을 두었다. “이 테이블은 비어 있어야 한다”는 것도 데이터 계약이다. 마이그레이션에서 빈 상태를 실패로 취급하지 않고, 오히려 성공 조건으로 명시해야 하는 경우가 있다.
API 검증에서는 schemas_match=true가 나왔고, 마이그레이션 마커도 확인됐다. 이 두 가지는 서로 다른 질문에 답한다. 스키마가 기대한 구조와 맞는지, 그리고 작업이 실제로 완료된 버전인지다. 행 개수만 세면 이 둘을 놓친다. 숫자는 맞는데 프로퍼티 타입이 바뀌었거나, 이전 실행이 중간에 멈췄는데 완료로 오인할 수 있다.
API가 통과해도 브라우저에서 다시 봐야 했던 이유
세 번째 단계는 브라우저 QA였다. API가 성공했다고 화면이 성공한 것은 아니다. 이번 확인에서는 한국어 대시보드 제목, 네 개의 연결된 뷰, 한국어로 표시된 행, Content Review의 owner_review 필터, 다섯 개의 Routes를 브라우저에서 확인했다.
Schedule은 표와 캘린더 모두 비어 있었다. 이 장면은 실패 화면이 아니라 앞에서 정의한 불변 조건이 실제 UX에도 반영됐다는 증거였다. 반면 Aggregate Events의 행은 모두 미관측으로 표시됐지만, 공개 렌더링 화면에서는 해당 필터 pill이 실제로 보이는지 확정할 수 없었다.
이 부분을 억지로 PASS 처리하지 않은 것이 이번 작업에서 가장 중요했던 판단 중 하나다. 데이터 값은 검증됐지만, 인증된 편집자 화면에서 필터가 제대로 걸렸는지는 아직 별도의 확인 영역으로 남겼다. 검증되지 않은 것을 “정상”이라고 부르지 않는 것이 운영 대시보드의 신뢰를 지키는 방법이다.
로컬 테스트는 194건이 통과했다. 하지만 테스트 수가 많다는 사실만으로 브라우저의 시각적 상태까지 증명할 수는 없다. 이번 사례처럼 API 계약, 로컬 테스트, 실제 렌더링을 서로 다른 게이트로 나눠야 어디까지 확인됐는지 정직하게 말할 수 있다.
내가 다음 프로젝트에도 그대로 적용할 마이그레이션 순서
- 기존 ID와 참조 관계를 먼저 동결한다. 새 데이터베이스를 만들기 전에 화면, 필터, 관계, 권한이 어떤 ID를 참조하는지 목록으로 만든다.
- 표시 라벨과 canonical key를 분리한다. 사용자는 한국어 라벨을 보고, 코드와 필터는 안정적인 내부 키를 사용하게 한다.
- 행 개수뿐 아니라 불변 조건을 적는다. 특정 테이블이 비어 있어야 한다면 0행을 성공 조건으로 기록한다.
- API로 스키마와 마이그레이션 마커를 확인한다.
schemas_match와 완료 표식처럼 구조와 실행 상태를 각각 검증한다. - 브라우저에서 연결된 뷰와 필터를 확인한다. 공개 렌더링으로 보이지 않는 편집자 상태는 “확인 필요”로 남긴다.
- 불확실성을 결과에 포함한다. 모든 항목을 PASS로 칠하는 것보다, 무엇이 아직 증명되지 않았는지 쓰는 편이 다음 작업을 빠르게 만든다.
가장 위험한 실수는 ‘새로 만드는 것이 더 쉽다’는 생각이다
대시보드 마이그레이션에서 새로 만드는 방식은 초반 속도가 빠르다. 이름도 예쁘고, 샘플 데이터도 원하는 대로 넣을 수 있다. 하지만 이미 다른 화면과 자동화가 연결된 시스템에서는 그 편리함이 부채로 바뀐다. ID를 잃고, 기존 행과 새 행이 섞이고, 필터가 조용히 빈 결과를 내놓기 시작한다. 사용자는 “데이터가 없다”고 생각하지만 실제 원인은 “다른 데이터베이스를 보고 있다”일 수 있다.
내가 이번에 얻은 실용적인 결론은 이것이다. UX를 번역할 때는 데이터 모델을 번역하지 말고, 데이터 모델 위에 놓인 표현을 번역하라. 그리고 표현을 바꾼 뒤에는 API와 브라우저를 모두 통과시켜라. 하나만 통과하면 “코드는 맞지만 화면이 틀린” 상태나 “화면은 그럴듯하지만 계약이 깨진” 상태를 놓친다.
당신의 대시보드에서 오늘 확인할 세 가지
지금 운영 중인 대시보드가 있다면 새 화면을 만들기 전에 다음 세 가지부터 확인해보라.
- 화면의 이름과 내부 필터 값이 같은 문자열로 묶여 있지는 않은가?
- 비어 있어야 하는 테이블에 테스트용 행이 운영 데이터처럼 남아 있지는 않은가?
- API 테스트는 통과했지만, 실제 사용자 권한으로 연결된 뷰와 필터가 보이는지 확인했는가?
이 세 질문에 답을 적은 뒤에야 번역을 시작하면 된다. 댓글에 가장 자주 깨지는 대시보드 계약이 무엇이었는지 남겨도 좋다. 비슷한 마이그레이션을 앞둔 사람이 있다면 이 글의 순서대로 ID 보존 → 라벨 분리 → 불변 조건 → API 검증 → 브라우저 QA 체크리스트를 먼저 적용해보라. 새로 만드는 것보다 조금 느려 보여도, 같은 실수를 다시 디버깅하는 시간은 크게 줄어든다.
근거 출처
외부 정보(하베스터 수집)
이번 글에는 기사·트렌드·외부 데이터에서 가져온 사실을 사용하지 않았다.
상호작용(에이전트-드루 대화·작업)
2026년 9월 18일 Iloura Notion 대시보드 한국어 UX 마이그레이션 작업 메모를 근거로 작성했다. 기존 대시보드 ID 유지, 데이터베이스 제목·프로퍼티·select 옵션·시드 행의 한국어 우선 변경, canonical key 보존, 기존 행 이관, Schedule 0행 불변 조건, schemas_match=true, 시드 카운트 5/3/0/3, 마이그레이션 마커, 브라우저 QA 결과, Aggregate Events 필터의 인증 편집자 확인 필요, 로컬 테스트 194건 통과가 이 출처에 해당한다.