React i18n 다국어 처리 빌드 크기 최적화 1

🌍 React i18n 다국어 처리 최적화, 실제 적용기

Autowini 서비스를 개발하면서 다국어(i18n) 지원을 위해 react-i18next를 도입해 사용하고 있었습니다.
처음에는 번역 JSON 파일을 import해서 사용하는 방식으로 구축했지만, 프로젝트가 커질수록 청크 파일 크기 증가와 초기 로딩 성능 저하 문제를 겪게 됐습니다.

문제가 됐던 다국어별 번들 크기 시각화

 

그래서 언어 처리 방식을 아예 바꾸고 i18n 번들 최적화를 적용했습니다. 그 과정을 공유해 보려고 합니다.

---

📌  기존 방식: import로 언어 번들 포함

처음에는 아래와 같이 다국어 JSON을 import해서 resources에 직접 넣는 방식이었습니다.

import ko from './locales/ko/translation.json';
import en from './locales/en/translation.json';

i18n.init({
  resources: {
    ko: { translation: ko },
    en: { translation: en },
  },
  lng: 'ko',
  fallbackLng: 'en',
});

 

이 방식의 장점은:

• 구조가 단순하고 빠르게 적용 가능
• 모든 번역이 앱과 함께 번들링되므로 로딩 속도는 빠름

하지만 단점도 명확했습니다:

• 언어 수가 늘어나고 JSON 파일이 커질수록 JS 번들 크기가 급격히 증가
• 결국 build 시간 증가, 초기 로딩 성능 저하로 이어짐

---

🔧  개선 방향: 정적 파일 + HttpBackend 로딩

그래서 다음과 같은 구조로 변경했습니다:

1. 언어 번역 JSON 파일을 /public/locales/{{lng}}/translation.json 경로에 분리
2. i18next-http-backend를 사용해 런타임에 해당 언어만 네트워크로 불러오도록 설정
3. 불필요한 번역 파일은 JS 청크에서 제거 → 빌드 크기 감소

import i18n from 'i18next';
import HttpBackend from 'i18next-http-backend';
import { initReactI18next } from 'react-i18next';

i18n
  .use(HttpBackend)
  .use(initReactI18next)
  .init({
    backend: {
      loadPath: '/locales/{{lng}}/translation.json',
    },
    lng: userLanguage,
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

 

🧠  HttpBackend는 정확히 뭘까요?

 

i18next-http-backend는 번역 리소스를 HTTP 요청으로 비동기 로드할 수 있게 도와주는 i18n 백엔드 플러그인입니다.
즉, 앱 초기 로딩 시 번역 JSON 파일을 import 해서 포함하는 게 아니라, 브라우저가 해당 언어에 필요한 파일만 네트워크를 통해 가져옵니다.

예: /locales/ar/translation.json 경로로 요청 → JSON 응답으로 번역 내용 제공

 

📉  왜 이게 빌드 최적화에 도움이 될까?

제가 사용하는 번들러는 Vite인데, 이는 내부적으로 Rollup을 사용합니다.
Rollup은 import된 파일을 모두 하나의 번들(JS 청크)로 합치기 때문에, JSON을 import 하면 JS 안에 모두 포함되죠.

하지만 /public 폴더에 있는 리소스는 정적으로 복사만 되며 번들에는 포함되지 않기 때문에 아래와 같은 효과가 있었습니다.

• JS 청크가 작아지고
• 빌드 시간 단축
• 초기 로딩 속도 향상

---

빌드 사이즈 줄어든 결과 & 느낀 점

Before

After

 

이전에 번역 파일을 모두 import해서 번들에 포함시키던 구조에서는 vite build를 실행할 때마다 경고 메시지를 자주 보게 되었는데, 이번 최적화를 통해 그 부담을 조금이나마 덜 수 있어서 다행이라고 생각합니다.

앞으로 프로젝트 규모가 커지고 번역 데이터가 늘어날수록, 이번 방식이 더욱 효과적으로 빛을 발할 것이라 확신합니다.