서비스 다국어 01 - 자동 번역 위젯에서 i18n으로
브라우저 자동 번역에 맡겨 두던 서비스를 한국어·영어·일본어 i18n 구조로 옮겼다. 화면 문구, DB 기준정보, 사용자 입력을 나눠 다룬 방식과 모든 화면을 언어별로 열어 본 전수검수 과정을 정리했다.
- #i18n
- #Vue
- #vue-i18n
- #next-intl
- #SpringBoot
- #QA
🧠 요약
- 자동 번역 위젯은 비동기 데이터를 놓치고, 새로고침마다 결과가 달랐다.
- 화면의 글을 어디서 왔는지로 나눴다. 화면 문구, DB 기준정보, 사용자 입력이다.
- 화면 문구는
vue-i18n, 기준정보는 API가 언어별 이름을 내려주고, 사용자 입력은 허용한 영역만 자동 번역한다. - 운영 DB 반영은 되돌릴 수 있게, 바로 검증할 수 있게 만들었다.
- 마지막으로 라우터의 모든 화면을 언어별로 열어 보는 전수검수와 용어 기준안으로 마무리했다.
고객사 이름과 수치는 빼고 과정만 적는다.
0. 문제: 브라우저 자동 번역에 맡긴 화면
업무 매칭 플랫폼은 구글 번역 위젯으로 화면 전체를 번역하고 있었다. 이 방식은 화면이 그려진 뒤에 DOM을 바꾼다. 그래서 다음 문제가 있었다.
- 비동기로 불러온 데이터와 일부 영역은 번역되지 않았다.
- 새로고침할 때마다 번역 결과가 달랐다.
- 번역된 문구가 길어져 레이아웃이 깨졌다.
- 다른 언어를 보다가 한국어로 돌아오면 번역 잔재가 남았다.
1. 글을 출처별로 나누기
자동 번역을 전부 끄는 것부터 시작했다. 앱 전체에 번역 제외 표식을 달고, 화면에 보이는 글을 출처별로 나눴다.
| 출처 | 예 | 처리 |
|---|---|---|
| 화면 문구 | 버튼, 안내 문구, 오류 메시지 | vue-i18n 번역 파일(KO·EN·JA) |
| 기준정보 | 메뉴, 업무 분류, 쿠폰, 지역 | API가 요청 언어에 맞는 이름을 응답 |
| 사용자 입력 | 업무 제목·본문, 채팅 | 허용한 영역만 선택형 자동 번역 |
| 원문 유지 | 개인정보, 파일명, URL | 번역하지 않음 |
사용자가 쓴 글은 미리 번역해 둘 수 없다. 그래서 여러 방식을 비교한 뒤, 승인된 영역만 자동 번역을 허용하는 선택형 방식을 골랐다. 개인정보와 파일명, URL은 허용 영역에서 뺐다.
2. 프론트엔드
언어 결정 순서를 한 곳으로
언어를 정하는 코드가 여러 곳에 흩어져 있었다. 이걸 하나로 모으고 순서를 정했다.
- 언어 쿠키
- 예전 번역 위젯이 남긴 쿠키
- 브라우저 언어
- 한국어
고른 언어는 HTML lang 속성과 API 요청의 Accept-Language 헤더에도 똑같이 실린다. 화면과 서버가 서로 다른 언어를 보는 일이 없게 하기 위해서다.
문구 말고도 바꿀 것들
- 날짜·시간 형식, 상태 라벨, 검증·오류·알림 문구를 locale 기준으로 바꿨다.
- 글자가 들어간 이미지는 언어별 이미지를 쓰도록 하고, 디자이너가 볼 등록 가이드를 남겼다.
CMS 기반 메인 사이트
메인 사이트(Next.js + Craft CMS)는 next-intl로 헤더, 푸터, 검색, FAQ, 블로그를 옮겼다. 이 과정에서 언어 쿠키가 중복으로 생기던 문제와, 개발 환경에서 태그 관리 스크립트가 자동 번역을 다시 끼워 넣던 문제도 고쳤다.
3. 백엔드: 화면만 번역해서는 끝나지 않는다
메뉴, 업무 분류, 쿠폰, 지역 같은 이름은 화면이 아니라 DB 기준정보에서 온다. 프론트 번역 파일만 고치면 이 이름들은 계속 한국어로 남는다. 서버가 내려주는 오류 메시지도 마찬가지였다.
- Spring Boot 백엔드의 코드·메뉴·쿠폰·행정구역 응답에 다국어 이름을 더했다.
- 요청의
Accept-Language를 보고 맞는 이름을 내려준다. 값이 비어 있으면 기본값으로 돌아간다. - 서버 오류 메시지도 영어·일본어 번역을 채웠다.
운영 반영: 되돌릴 수 있게, 검증할 수 있게
운영 DB를 건드리는 작업이라 다음을 지켰다.
- 다국어 컬럼 이관 스크립트와 운영 DB 반영 SQL을 따로 만들었다.
- 반영 SQL에는 검증 쿼리를 같이 넣어, 넣은 값이 기준과 맞는지 바로 확인하게 했다.
- 개발 DB와 운영 SQL의 번역값 차이를 표로 뽑고, 개발 DB를 운영 값에 맞추는 보정 SQL을 만들었다.
- 나중에 추가된 기준정보도 같은 방식으로 반영했다.
4. 전수검수: 모든 화면을 언어별로 연다
코드에서 번역 키만 확인하면 실제 화면에서 빠진 곳을 놓친다. 그래서 라우터에 등록된 경로를 모두 뽑아 검수표를 만들고, 계정 유형별로 각 화면을 실제로 열어 판정했다.
| 항목 | 확인한 것 |
|---|---|
| 정적 문구 | KO·EN·JA 화면 문구가 모두 번역됐는지 |
| 동적 콘텐츠 | API·DB·사용자 입력이 정책대로 번역되거나 원문을 유지하는지 |
| 한국어 복귀 | 다른 언어를 본 뒤 한국어로 돌아왔을 때 번역 잔재가 없는지 |
| 레이아웃 | 번역 문구 길이 때문에 화면이 깨지지 않는지 |
| 콘솔·API | 언어를 바꿀 때 오류가 나지 않는지 |
판정 기준도 먼저 정했다.
- 사람 이름, 파일명, 계좌·법인 정보처럼 원문을 유지해야 하는 값은 실패로 보지 않는다.
- 판정은 배포본 기준으로 하고, 재현한 문제는 고친 뒤 개발 서버에서 다시 확인한다.
- 계정이 없어 열 수 없는 화면은 막힌 이유를 함께 적는다.
용어 기준안: 같은 말은 같은 번역으로
검수하다 보니 같은 한국어가 화면마다 다른 영어·일본어로 번역돼 있었다. 예를 들면 "고객센터", "기업", "충전" 같은 말이다.
용어마다 지금 섞여 있는 표현과 바꿀 곳을 정리한 기준안을 만들어 확정받고, 프론트 번역 파일과 DB 기준정보에 같은 값을 한꺼번에 적용했다. 문장 속에서 뜻이 달라지는 경우는 바꾸지 않도록 예외도 적어 두었다.
🔄 회고 및 인사이트
새로 알게 된 점
- 다국어는 프론트엔드 작업이 아니다. 화면에 보이는 글의 상당 부분이 DB와 서버에서 온다.
- "번역됐다"를 확인하려면 코드가 아니라 화면을 봐야 한다. 라우터에서 경로를 뽑아 검수표를 만든 게 가장 효과가 컸다.
관점의 변화
처음에는 번역 파일을 채우는 일이라고 생각했다. 실제로는 "이 글은 어디서 오는가"를 정리하는 일이었고, 그 분류가 정해지자 나머지 결정이 따라왔다.