React 프로젝트에 i18n 적용하기 (react-i18next)
다국어를 지원하는 웹 서비스를 만들기 위해 i18n을 적용했다.
React 기반 프로젝트에서 react-i18next를 이용해 간단하게 다국어 지원을 설정할 수 있다.
이번 글에서는 국제화(i18n)의 개념부터 적용 과정까지 차근차근 정리한다.
0. i18n이란?
i18n은 Internationalization의 약어다.
영어 단어 Internationalization에서 i로 시작해 n으로 끝나는 사이에 18개의 문자가 들어있기 때문에 i18n이라고 부른다.
웹 서비스에서 i18n은 사용자의 언어, 국가, 지역 환경에 맞게 텍스트나 날짜, 숫자 포맷 등을 다국어로 지원하는 기능을 말한다.
예를 들어,
"환영합니다"→ 한국어"Welcome"→ 영어"欢迎"→ 중국어
이런 식으로 텍스트를 사용자 언어에 맞게 바꿔주는 것이다.
1. 왜 react-i18next를 선택했는가?
i18n을 React에서 적용할 수 있는 라이브러리는 몇 가지가 있다. 그 중 react-i18next를 선택한 이유는 다음과 같다:
| 이유 | 설명 |
|---|---|
| 공식 지원 | i18next의 공식 React 바인딩 |
| 문서가 풍부하고 안정적 | 사용자가 많고 레퍼런스가 많음 |
| 간단한 API | useTranslation() 훅만으로도 충분히 사용 가능 |
| 브라우저 언어 감지 지원 | 자동 언어 설정을 쉽게 구현 가능 |
| Lazy loading, namespace 등 확장성 높음 | 필요 시 세분화된 설정도 가능 |
특히, 기존 React 프로젝트에 부담 없이 적용할 수 있고 컴포넌트 단위로 번역 키를 관리할 수 있어서 개발 및 유지보수가 용이하다.
2. 패키지 설치
npm install i18next react-i18next i18next-browser-languagedetector| 패키지 | 설명 |
|---|---|
i18next | 국제화 핵심 라이브러리 |
react-i18next | React 연동을 위한 바인딩 |
i18next-browser-languagedetector | 브라우저 언어 자동 감지 기능 제공 |
3. i18n 설정 파일 만들기
src/i18n.js 파일을 생성하고 다음처럼 설정을 작성한다.
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import translationEN from './locales/en/translation.json';
import translationKO from './locales/ko/translation.json';
const resources = {
en: { translation: translationEN },
ko: { translation: translationKO },
};
i18n
.use(LanguageDetector)
.use(initReactI18next)
.init({
resources,
fallbackLng: 'ko',
interpolation: {
escapeValue: false,
},
});
export default i18n;4. main 파일에 i18n 연결
main.jsx 또는 index.js에서 i18n을 import해 초기화되도록 한다.
import './i18n';5. 번역 리소스 생성
src/
├── locales/
│ ├── en/
│ │ └── translation.json
│ └── ko/
│ └── translation.jsonlocales/ko/translation.json
{
"welcome": "환영합니다!",
"subtitle": "이건 한글이에요"
}locales/en/translation.json
{
"welcome": "Welcome!",
"subtitle": "This is English"
}6. 컴포넌트에서 사용하기
import { useTranslation } from 'react-i18next';
const Home = () => {
const { t } = useTranslation();
return (
<div>
<h1>{t('welcome')}</h1>
<p>{t('subtitle')}</p>
</div>
);
};7. 자주 사용하는 번역 키 작성 팁
i18n을 적용하다 보면 번역 키를 어떻게 구성하고 유지할지에 대한 고민이 생긴다.
특히 프로젝트 규모가 커질수록 번역 키 관리가 중요해진다.
1. 기능/화면 단위로 네임스페이스 분리하거나 접두사 사용하기
예: landing.title, dashboard.subtitle, profile.editButton
{
"landing": {
"title": "여기에 오신 것을 환영합니다!"
},
"dashboard": {
"greeting": "안녕하세요, {{username}}님"
}
}2. 컴포넌트와 1:1 대응되는 구조
각 컴포넌트별로 필요한 텍스트만 독립적으로 관리할 수 있어서 유지보수가 편하다.
예: BadgePreview.empty, CommitChart.tooltip, LanguageToggle.label
3. 공통 키는 따로 빼기
프로젝트 전반에서 반복되는 텍스트(버튼, 상태 메시지 등)는 공통으로 분리해서 관리하는 것이 좋다.
{
"button": {
"ok": "확인",
"cancel": "취소"
},
"common": {
"loading": "로딩 중..."
}
}4. 변수를 포함한 메시지도 지원
i18next는 {{ }} 구문으로 변수를 받을 수 있다.
{
"dashboard.greeting": "안녕하세요, {{username}}님"
}t('dashboard.greeting', { username: '민승용' });5. 언어 전환 버튼 만들기
사용자가 직접 언어를 바꿀 수 있도록 전환 버튼을 제공할 수 있다.
import { useTranslation } from 'react-i18next';
const LanguageToggle = () => {
const { i18n, t } = useTranslation();
const toggleLanguage = () => {
const nextLang = i18n.language === 'ko' ? 'en' : 'ko';
i18n.changeLanguage(nextLang);
};
return (
<button onClick={toggleLanguage}>
{t('button.changeLanguage')} ({i18n.language})
</button>
);
};결론
- 키는 의미 중심, 계층적 구조로 작성한다.
- 공통 키와 화면별 키를 분리해 관리한다.
- 번역 키 작성 습관이 나중에 협업과 유지보수 효율성에 큰 영향을 준다.
더 많은 언어가 추가되거나 서버와 연동해야 하는 상황이라면
namespace 분리, lazy loading 등 고급 설정도 고려할 수 있다.
기초적인 구조를 처음에 잘 잡아두는 게 중요하다.
마무리
react-i18next를 사용하면 React 프로젝트에서 간단한 설정만으로 국제화를 적용할 수 있다.
전역 설정, 컴포넌트 단위 사용, 언어 전환까지 한 번에 구성할 수 있고, 이후 lazy loading이나 서버 연동 등도 쉽게 확장 가능하다.
