React + TypeScript + Vite 에서 `i18next`로 다국어 처리하기

설정 개요

이 프로젝트에서는 다음을 사용해 다국어를 구현합니다

1. 라이브러리:
   • i18next (번역 핵심)
   • react-i18next (React 통합)
   • i18next-http-backend (JSON 파일로 번역 관리)
   • i18next-browser-languagedetector (브라우저 언어 자동 감지)
2. 파일 구조:
   • 번역 파일은 public/locales/{lng}.translation.json 형식으로 저장.
   • i18n.ts에서 i18next 초기화.
   • vite-plugin-next-react-router를 사용하여 레이아웃 기반 초기화.

1. i18n.ts - i18next 초기화

tsx
복사편집
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import HttpBackend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

i18n
  .use(HttpBackend) // JSON 번역 파일 로드
  .use(LanguageDetector) // 브라우저 언어 감지
  .use(initReactI18next) // React와 i18n 연결
  .init({
    fallbackLng: "en", // 기본 언어
    supportedLngs: ["en", "ko"], // 지원하는 언어
    interpolation: {
      escapeValue: false, // React에서 XSS 방어 필요 없음
    },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json", // 번역 파일 경로
    },
    debug: true, // 디버깅 활성화
  });

export default i18n;

2. 번역 파일 생성

public/locales/ko.translation.json (한국어)

{
  "welcome": "우리 웹사이트에 오신 것을 환영합니다!",
  "about": "우리에 대해 더 알아보세요.",
  "change_language": "언어 변경",
  "login": "로그인"
}

public/locales/en.translation.json (영어)

{
  "welcome": "Welcome to our website!",
  "about": "Learn more about us.",
  "change_language": "Change Language",
  "login": "Login"
}

3. i18n 초기화 - _layout.tsx에서

vite-plugin-next-react-router를 사용하면 모든 페이지에 공통으로 적용되는 레이아웃 파일에서 i18n을 초기화합니다.

_layout.tsx

import React from "react";
import { Outlet } from "react-router-dom";
import "../i18n"; // i18n 초기화

const Layout = () => {
  return (
    <div>
      <header>
        <h1>My Application</h1>
      </header>
      <main>
        <Outlet /> {/* 각 페이지가 렌더링됨 */}
      </main>
    </div>
  );
};

export default Layout;

4. 다국어 UI 구현

IndexPage.tsx

import { useTranslation } from "react-i18next";

const IndexPage = () => {
  const { t, i18n } = useTranslation();

  // 언어 변경 핸들러
  const handleChangeLanguage = (
    event: React.ChangeEvent<HTMLSelectElement>,
  ) => {
    const selectedLanguage = event.target.value;
    i18n.changeLanguage(selectedLanguage);
  };

  return (
    <div>
      <header>
        <select
          id="language-select"
          value={i18n.language}
          onChange={handleChangeLanguage}
        >
          <option value="en">English</option>
          <option value="ko">한국어</option>
          {/* 다른 언어 추가 가능 */}
        </select>
      </header>
      <h2 className="mb-4 text-[28px] font-bold">{t("login")}</h2>
    </div>
  );
};

export default IndexPage;

---

5. 결과물 예시

1. 초기 로딩 시 브라우저 언어에 맞는 번역 파일(en 또는 ko)이 자동으로 로드됩니다.
2. 사용자가 드롭다운에서 언어를 변경하면 i18next가 즉시 언어를 변경합니다.
3. 번역 파일은 /locales/{언어}/translation.json에서 가져옵니다.

6. 주요 체크포인트

• 경로 설정: 번역 파일은 public/locales 디렉토리에 위치해야 하며, loadPath가 이를 가리키도록 설정.
• i18n 초기화 위치: main.tsx가 아닌 _layout.tsx에서 초기화.
• 번역 키 사용: t("key")를 사용하여 번역을 가져오며, 미번역된 키는 그대로 표시됩니다.
• 언어 감지: i18next-browser-languagedetector로 브라우저 언어를 자동 감지.

이제 프로젝트가 다국어를 지원하며, 사용자는 손쉽게 언어를 전환할 수 있습니다. 🚀