React에서 i18next로 다국어 지원 구현

개요

리액트 애플리케이션에 다국어를 도입하면 사용자 경험이 크게 개선된다. 이 글은 react i18next 설정 과정을 처음 접하는 개발자도 이해할 수 있게 단계별로 정리한다. 핵심은 초기화, 리소스 구조, 컴포넌트 적용, 언어 전환이다.

i18next와 react-i18next 이해

i18next란?

i18next는 자바스크립트 기반의 국제화 프레임워크다. 번역 리소스를 관리하고, 로케일 감지와 폴백을 지원한다. react-i18next는 리액트 친화적 훅과 HOC를 제공한다.

설치 및 초기 설정

필수 패키지 설치

간단한 설치 명령은 다음과 같다. 필요한 모듈만 추가하면 빠르게 시작할 수 있다.

npm install i18next react-i18next i18next-http-backend i18next-browser-languagedetector

i18n 초기화 파일

프로젝트 루트에 i18n.js 파일을 만든다. 여기서 번역 리소스 위치와 기본 언어를 설정한다.

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import HttpApi from 'i18next-http-backend';

i18n
  .use(HttpApi)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'ko'],
    debug: false,
    interpolation: { escapeValue: false },
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json'
    }
  });

export default i18n;

번역 파일 구조

정리된 폴더 구조가 유지보수에 유리하다. 보통 locales 폴더에 언어별 폴더를 둔다.

/public/locales/en/translation.json
/ public/locales/ko/translation.json

// 예시: /public/locales/ko/translation.json
{
  "welcome": "환영합니다",
  "description": "리액트 애플리케이션 다국어 테스트"
}

컴포넌트에서 번역 사용하기

useTranslation 훅

가장 흔한 방법은 useTranslation 훅을 사용하는 것이다. 간결하고 재사용하기 쉽다.

import React from 'react';
import { useTranslation } from 'react-i18next';

function Home() {
  const { t } = useTranslation();
  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
    </div>
  );
}

export default Home;

언어 전환 구현

언어 전환은 간단한 버튼이나 셀렉트로 구현할 수 있다. changeLanguage 메서드를 사용하면 즉시 언어가 바뀐다.

import React from 'react';
import { useTranslation } from 'react-i18next';

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const change = (lng) => {
    i18n.changeLanguage(lng);
  };

  return (
    <div>
      <button onClick={() => change('en')}>EN</button>
      <button onClick={() => change('ko')}>KO</button>
    </div>
  );
}

export default LanguageSwitcher;

서버 사이드와 정적 빌드 고려사항

서버사이드 렌더링을 사용하는 경우 설정이 약간 달라진다. 백엔드 로더 대신 리소스를 직접 임포트하거나, 서버에 맞는 로더를 사용한다. 정적 사이트는 빌드 단계에서 필요한 번역을 포함시키는 방식이 간편하다.

네임스페이스와 동적 로딩

큰 앱에서는 네임스페이스로 기능별 파일을 분리하는 것이 좋다. 렌더링 성능을 위해 필요한 네임스페이스만 로드하도록 구성할 수 있다. 이때 backend 옵션의 loadPath를 적절히 설정한다.

실전 적용 시 권장사항

• 키는 의미 있는 이름으로 관리한다. 의미 없는 숫자열은 피한다.
• 문장 단위보다 문맥을 고려해 키를 설계한다.
• 동적 값은 interpolation을 사용해 관리한다.
• 번역 누락을 발견하면 fallback 설정을 확인한다.

마무리

react i18next 설정은 초기 구성만 잘하면 확장성이 좋다. 번역 파일 구조와 네임스페이스 전략을 먼저 설계하면 유지보수가 쉬워진다. 위 예제는 i18n react 예제 로 바로 적용해 볼 수 있는 최소 구성이다. 필요에 따라 로더와 감지기를 조합해 환경에 맞게 확장하면 된다.