글로벌 서비스를 위한 다국어(i18n) 개발기: 번역 자동화부터 타임존 대응까지

글로벌 서비스를 위한 다국어(i18n) 개발기: 번역 자동화부터 타임존 대응까지

자율주행 물류 서비스가 현장에서 실질적인 생산성 향상을 증명해내면서, 감사하게도 글로벌 시장 진출을 위한 준비를 시작하게 되었습니다. 글로벌 서비스의 핵심은 단연 다국어 지원(Internationalization, i18n)입니다.

하지만 단순히 텍스트를 번역하는 것을 넘어, 통화, 숫자, 날짜 형식의 로컬라이징부터 타임존 대응, 글로벌 인프라 최적화까지 프론트엔드 엔지니어가 고민해야 할 지점은 생각보다 훨씬 넓고 깊었습니다. 이번 글에서는 그 치열했던 고민의 과정과 해결책을 공유하고자 합니다.

---

1. 다국어 매핑의 기본과 UI 파편화 해결

프론트엔드에서는 주로 react-i18next를 사용하여 언어별 JSON 언어팩을 Key-Value 기반으로 매핑합니다. 하지만 현장에서는 단순히 텍스트를 치환하는 것만으로 해결되지 않는 문제들이 발생합니다.

텍스트 길이에 따른 레이아웃 붕괴 대응

한국어로는 4글자면 충분한 "저장 완료"가 영어로는 "Successfully Saved", 독일어로는 "Erfolgreich gespeichert"가 됩니다. 이 과정에서 디자인이 깨지는 것을 막기 위해 다음과 같은 전략을 사용했습니다.

• Trans 컴포넌트 활용: 번역 값 내부에 HTML 요소를 포함하거나, 특정 부분에만 볼드/컬러 처리가 필요한 복잡한 문장을 안전하게 렌더링합니다.
• Navigator language API: Navigator language Web API를 통해 사용자의 브라우저 언어 설정을 감지, 첫 진입 시 최적의 언어를 우선 표출하여 진입 장벽을 낮췄습니다.

---

2. 개발자가 번역의 병목이 되지 않는 자동화 시스템 구축

서비스가 성장할수록 UI는 방대해지고, 일일이 Key를 달고 JSON을 업데이트하는 방식은 한계에 다다랐습니다. 특히 기획자, 번역 담당자와 엑셀/피그마로 소통하며 수동으로 복사-붙여넣기를 하는 과정은 휴먼 에러의 온상이었습니다.

이를 해결하기 위해 번역 담당자의 엑셀 작업이 즉시 프로젝트의 코드가 되는 시스템을 구축했습니다.

① i18next-parser를 활용한 스캐폴딩 자동화

개발자가 코드에 t('어떤 내용의 버튼')라고 쓰기만 하면, i18next-parser 스크립트가 전체 소스 코드를 스캔하여 JSON 파일의 구조(Scaffolding)를 자동으로 생성합니다. 이제 개발자는 JSON 파일을 수동으로 편집할 필요가 없습니다.

• 현재 i18next-parser는 i18next-cli로 통합된 것 같습니다. 이전에 제가 구현한 부분들에 대한 기능을 CLI로 정식 제공하고 있는 듯 합니다.

② 엑셀 기반 양방향 번역 파이프라인과 통합 검수 프로세스

번역 담당자에게 친숙한 엑셀(Excel)을 중심(Single Source of Truth)으로 삼아, 기획부터 최종 디자인 검수까지 이어지는 "End-to-End 다국어 개발 프로세스"를 구축했습니다.

특히, JSON 번역 파일과 엑셀 파일을 상호 변환하는 스크립트를 직접 구축하여 기술적 병목을 해결했습니다.

• JSON to Excel: 프로젝트 내의 다국어 JSON 파일을 스캔하여 키와 언어별 값이 매핑된 테이블 형태의 엑셀로 추출합니다.
• Excel to JSON: 번역가가 수정한 엑셀 파일을 읽어와 다시 프로젝트 내의 JSON 언어팩으로 자동 변환하여 반영합니다.

또한, 현재 프로젝트에 적용된 실시간 번역 현황을 스토리북 내부에 시각화 페이지로 구성했습니다. 이를 통해 번역 담당자는 별도의 개발 도구 없이도 현재 적용된 번역 상태를 엑셀처럼 한눈에 확인하고, 필요한 경우 즉시 엑셀로 다운로드할 수 있는 환경을 마련했습니다.

flowchart TD
    subgraph "1. 개발 및 추출"
        Code[React Source Code] -- "i18n:extract" --> JSON_Raw[JSON 스캐폴딩]
        JSON_Raw -- "구축된 JSON-to-Excel 스크립트" --> Excel[번역용 엑셀 파일]
    end

    subgraph "2. 협업 및 번역"
        Excel -- "기획/번역가 작업" --> Excel_Done[번역 완료 엑셀]
        Excel_Done -- "구축된 Excel-to-JSON 스크립트" --> JSON_Final[프로젝트 반영]
    end

    subgraph "3. 배포 및 검수"
        JSON_Final -- "CI/CD 자동 빌드" --> SB_Deploy{환경별 스토리북 배포}
        SB_Deploy --> SB_Visual["스토리북 내 번역 시각화/다운로드"]
        SB_Deploy --> SB_App["환경별 UI 컴포넌트 (Dev/QA/Prod)"]

        SB_Visual & SB_App --> Designer["디자이너/기획자 최종 시각 검수"]
    end

    style Excel_Done fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style SB_Deploy fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style Designer fill:#fff3e0,stroke:#ef6c00,stroke-width:2px

더 나아가 단순히 로컬에서만 확인하는 것이 아니라, 개발(Dev), 테스트(QA), 운영(Prod) 각 단계의 배포본과 동일한 형상의 스토리북을 상시 호스팅했습니다. 이를 통해 디자이너는 실제 서비스가 배포되기 전, 해당 환경의 스토리북 주소에 접속하여 언어별 UI 터짐 현상이나 번역 어색함을 즉시 파악하고 피드백할 수 있는 체계를 갖추게 되었습니다.

---

3. 스토리북을 활용한 시각적 검수 환경 혁신

번역된 텍스트가 실제 UI에서 어떻게 보이는지, 글자 수가 넘치지는 않는지 확인하는 과정은 매우 고통스럽습니다. 이를 위해 환경별로 동기화된 호스팅 스토리북을 적극 활용했습니다.

1. 언어 변경 컨트롤러 통합: 스토리북 상단 툴바에 언어 선택 메뉴를 추가하여, 클릭 한 번으로 모든 컴포넌트의 언어를 즉시 변경하며 테스트할 수 있게 했습니다.
2. 번역 현황 시각화 테이블: 현재 프로젝트에 적용된 모든 번역 키와 값을 스토리북 내의 별도 페이지로 시각화했습니다. 여기서 바로 엑셀 다운로드가 가능하게 하여, 기획자가 현재 배포된 번역이 무엇인지를 개발자에게 묻지 않고 직접 확인할 수 있도록 했습니다.

이 체계는 개발-디자인-기획 간의 피드백 루프를 비약적으로 단축시켰습니다. 디자이너는 배포된 스토리북 주소만으로도 다국어 디자인 검수를 완결할 수 있게 되었습니다.

---

4. 데이터 로컬라이징: Intl API와 타임존의 늪

텍스트 번역보다 더 까다로운 것이 날짜, 숫자, 통화의 로컬라이징입니다.

Intl Web API: 브라우저가 제공하는 강력한 표준

언어별 날짜 표기법(YYYY-MM-DD vs DD/MM/YYYY)을 일일이 공부할 필요가 없습니다. Intl Web API를 활용하면 브라우저가 알아서 해당 국가의 표준 형식으로 변환해 줍니다.

// react-i18next 내에서 Intl 활용 예시 (날짜 포맷팅)
t('DATE_FORMAT', { 
  val: new Date(), 
  formatParams: { val: { year: 'numeric', month: 'long', day: 'numeric', weekday: 'long' } } 
});

타임존(Timezone)과 에뮬레이션 테스트

서버와는 항상 ISO8601 포맷으로 통신하여 데이터의 무결성을 유지하고, 클라이언트에서만 사용자의 로컬 타임존으로 변환하여 표출합니다.

크롬 데브툴의 센서 에뮬레이션 기능을 활용하면 한국에 앉아서도 브라우저의 위치와 타임존을 뉴욕이나 도쿄로 설정하여, 서버에서 내려온 시간이 현지 시간으로 정확히 변환되는지 실시간으로 검증할 수 있습니다.

---

5. 글로벌 서비스의 성능: AWS CloudFront 전략

물리적 거리가 먼 국가의 사용자는 에셋 다운로드 속도에서 소외될 수 있습니다. 이를 위해 AWS CloudFront를 활용한 엣지 캐싱 전략을 최적화했습니다.

• index.html의 무효화(Invalidation): 배포 시점에 index.html 캐시만 무효화하여 사용자가 항상 최신 버전을 보게 하되, 해싱된 나머지 정적 파일(main.hash.js 등)은 강력한 엣지 캐싱을 적용해 첫 로딩 속도를 극대화했습니다.

---

6. 미래를 준비하며: AI 번역과 브라우저 로컬 AI

최근에는 번역 담당자의 단순 작업을 줄이기 위해 Claude AI를 도입했습니다. 번역 전용 Skill을 만들어 JSON 초안을 자동으로 생성하고, 문맥에 맞는 적절한 표현을 추천받는 과정을 자동화하고 있습니다.

더 나아가 브라우저 로컬 AI 기반의 Translation Web API가 상용화된다면, 런타임에서 사용자의 기기 성능을 활용해 즉각적이고 완벽한 로컬라이징이 이루어지는 시대가 올 것이라 기대하고 있습니다.

---

마치며: 품질은 소통의 도구에서 시작된다

이번 다국어 대응 프로젝트를 통해 얻은 가장 큰 배움은 엔지니어링은 단순히 코드를 짜는 것이 아니라, 협업을 위한 최적의 도구를 설계하는 것이라는 점입니다.

엑셀라는 공통의 언어로 기획자와 번역가를 연결하고, 스토리북이라는 시각적 도구로 디자이너와 소통하며, 인프라와 표준 API로 글로벌 사용자를 포용하는 과정. 이 모든 여정이 서비스의 품질을 만들고 팀의 확신을 더해주었습니다.

---