React i18n 시스템 설계 가이드 – 다국어 지원부터 성능 최적화까지
🌐 React 앱에서 다국어(i18n) 시스템 설계와 최적화 전략
글로벌한 사용자에게 서비스를 제공하려면 단순 번역을 넘어서 체계적인 다국어(i18n) 시스템이 필요합니다.
React 앱에서 다국어를 효과적으로 구현하기 위해서는
언어별 리소스 분리, 초기 로딩 전략, 사용자 언어 감지, UX와 SEO 고려
까지 전방위적 설계가 중요합니다.
이번 글에서는 실무에서 가장 널리 사용되는 react-i18next를 중심으로, 다음과 같은 내용을 중점적으로 다룹니다:
- 📦 리소스 파일 구성 전략
- 🌍 브라우저 언어 감지와 URL 연동
- 📑 번역 키 관리 요령과 네임스페이스
- 🚀 성능 최적화를 위한 Lazy Load 전략
- 🛠 실전 적용 시 유의할 UX 요소들
🔧 1. react-i18next 기본 설정
먼저 react-i18next는 React와 i18next의 연결 다리 역할을 해주는 공식 라이브러리입니다.
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend기초 설정 파일 (i18n.ts 또는 i18n.js)
{`import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import HttpBackend from 'i18next-http-backend';
i18n
.use(HttpBackend)
.use(LanguageDetector)
.use(initReactI18next)
.init({
fallbackLng: 'en',
supportedLngs: ['en', 'ko', 'ja'],
ns: ['common'],
defaultNS: 'common',
interpolation: {
escapeValue: false
}
});
export default i18n;`}여기서 HttpBackend를 사용하면 언어 리소스를 JSON 파일로 분리하고 동적으로 로딩할 수 있습니다.
📂 2. 다국어 리소스 구조 설계
언어 리소스를 어떻게 분리하고 구조화하느냐에 따라 번역 품질과 유지보수 난이도가 결정됩니다.
public/
└── locales/
├── en/
│ └── common.json
├── ko/
│ └── common.json
└── ja/
└── common.json모듈 또는 페이지 단위로 나누고 싶다면 다음처럼 네임스페이스를 추가할 수 있습니다:
public/
└── locales/
├── en/
│ ├── common.json
│ ├── home.json
│ └── dashboard.json
├── ko/
│ ├── common.json
│ ├── home.json
│ └── dashboard.json
└── ...팁: 네임스페이스를 모듈과 1:1 매칭시키면 확장성과 협업이 좋아집니다.
🧠 3. 번역 키 관리 전략
하드코딩된 문자열은 금물입니다. useTranslation 훅을 통해 항상 키 기반으로 관리합니다.
{`import { useTranslation } from 'react-i18next';
const { t } = useTranslation();
<h1>{t('home.title')}</h1>`}좋은 번역 키 네이밍은 다음과 같은 기준을 따릅니다:
- 페이지 or 모듈 + 역할 중심 (예:
home.title,login.submitButton) - 중복 최소화, 재사용 용이
- JSON 구조도 직관적이게
{`// locales/en/common.json
{
"home": {
"title": "Welcome",
"description": "This is the homepage."
}
}`}🌍 4. 브라우저 언어 감지 및 URL 연동
i18next-browser-languagedetector를 통해 사용자 브라우저의 언어 설정을 자동 감지할 수 있습니다.
{`i18n.use(LanguageDetector).init({
detection: {
order: ['querystring', 'cookie', 'localStorage', 'navigator'],
caches: ['cookie']
}
});`}👉 querystring 기반으로 하면 ?lng=ko 와 같은 URL로 접근해 언어 설정이 가능합니다.
또한 Next.js, Remix 등에서는 /ko, /en 과 같은 라우트 기반 언어 설정도 가능합니다.
🚀 5. 성능 최적화: Lazy Load + Chunk 분리
다국어 리소스를 앱 번들에 포함시키면 초기 로딩 속도에 영향을 줄 수 있습니다. 이를 방지하려면 다음 전략을 사용하세요:
- HttpBackend + lazy load: 필요한 언어만 로딩
- 언어별 리소스를 외부 CDN 또는 경량 API에서 제공
- 초기 로딩 시 fallbackLng만 선로딩
{`i18n.init({
backend: {
loadPath: '/locales/{{lng}}/{{ns}}.json'
}
});`}→ 언어별로 별도 JSON을 요청하며, 네임스페이스도 동적으로 관리 가능
🎨 6. UX를 위한 다국어 설계 팁
단순히 번역만 있다고 좋은 다국어 UX는 아닙니다. 다음 요소를 고려해보세요:
- ✅ 언어 전환 UI: 국기 아이콘, 텍스트 선택, 드롭다운
- ✅ 전환 후 유지: 이전 페이지 or 현재 위치 그대로 유지
- ✅ R2L 언어 (아랍어 등) 대비 레이아웃 대응
- ✅ 숫자, 날짜 포맷 대응:
Intl또는dayjs
예:
{`new Intl.NumberFormat('ko-KR', {
style: 'currency',
currency: 'KRW'
}).format(123456);`}🧪 7. 테스트 환경에서도 i18n 고려하기
Jest 또는 Testing Library를 사용할 경우 useTranslation 훅을 Mock 처리하거나 기본 텍스트를 반환하도록 설정합니다.
{`jest.mock('react-i18next', () => ({
useTranslation: () => ({
t: (key) => key
})
}));`}또는 i18nTestProvider를 별도로 구성해 테스트 전용 리소스를 주입해도 좋습니다.
✅ 마무리 요약
다국어 시스템은 단순 번역 기능을 넘어서 앱 전체의 구조와 UX에 깊은 영향을 미치는 설계 요소입니다.
특히 글로벌 서비스를 준비한다면 초기부터 다국어 구조를 고려하는 것이 유지보수에 큰 도움이 됩니다.
| 항목 | 전략 요약 |
|---|---|
| 언어 파일 구성 | public/locales/ 언어/네임스페이스.json |
| 번역 키 관리 | t('module.key') 구조, JSON 키 직관성 유지 |
| 성능 최적화 | HttpBackend + Lazy load + CDN 분리 |
| UX 개선 | 전환 유지, 포맷 대응, 전환 UI 제공 |
| 테스트 대응 | useTranslation mock 또는 테스트 Provider 사용 |
i18n은 앱의 확장성과 글로벌 경쟁력을 좌우합니다.
지금부터라도 올바른 구조를 고민하며 구축해보세요! 🌍🌐