Next.js App Router에서 Tolgee를 사용한 React 다국어 지원 구현 가이드

📅 2025-06-11T02:23:06Z 👤 Fadil Natakusumah 🏷️ 개발

완성도:

0.8

🤖 AI 추천

Next.js 환경에서 React 애플리케이션을 개발하며 다국어 지원(i18n)을 효율적으로 구현하고자 하는 프론트엔드 개발자에게 이 콘텐츠를 추천합니다. 특히 Tolgee 라이브러리의 설정 방법, 언어 스위처 구현 등 실질적인 코드 예제를 통해 즉시 적용 가능한 인사이트를 얻을 수 있습니다.

🔖 주요 키워드

React Next.js Tolgee 다국어 지원 i18n App Router 국제화 프론트엔드 개발

Next.js App Router에서 Tolgee를 사용한 React 다국어 지원 구현 가이드

핵심 기술

본 문서는 Next.js 13+ App Router 환경에서 Tolgee 라이브러리를 활용하여 React 애플리케이션에 다국어 지원을 손쉽게 구현하는 방법을 안내합니다.

기술적 세부사항

Tolgee 소개: 웹 앱을 위한 현대적인 i18n 도구로, 인컨텍스트 번역, TypeScript 지원, React 통합이 용이하며 i18next보다 설정 및 관리가 간편함.
패키지 설치: npm install @tolgee/react tolgee 명령어로 필요한 패키지를 설치합니다.
Tolgee 설정: lib/tolgee.ts 파일에 Tolgee 인스턴스를 생성하고 DevTools, ReactPlugin, FormatSimple 플러그인을 적용합니다. API URL, API 키, 기본 언어 및 사용 가능한 언어 목록을 환경 변수 및 설정으로 지정합니다.
typescript // lib/tolgee.ts import { Tolgee, DevTools, FormatSimple, ReactPlugin } from '@tolgee/react'; export const tolgee = Tolgee() .use(DevTools()) // Optional, for inline editing .use(ReactPlugin()) .use(FormatSimple()) .init({ apiUrl: process.env.NEXT_PUBLIC_TOLGEE_API_URL!, apiKey: process.env.NEXT_PUBLIC_TOLGEE_API_KEY!, language: 'en', availableLanguages: ['en', 'id'], fallbackLanguage: 'en', });
Provider 설정: app/layout.tsx 파일에서 TolgeeProvider로 애플리케이션을 감싸 Tolgee 컨텍스트를 제공합니다.
typescript // app/layout.tsx import './globals.css'; import { TolgeeProvider } from '@tolgee/react'; import { tolgee } from '@/lib/tolgee'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en"> <body> <TolgeeProvider tolgee={tolgee}>{children}</TolgeeProvider> </body> </html> ); }
번역 사용: app/page.tsx에서 useTranslate 훅을 사용하여 t 함수로 텍스트를 번역합니다.
typescript // app/page.tsx 'use client'; import { useTranslate } from '@tolgee/react'; export default function HomePage() { const { t } = useTranslate(); return ( <h1>{t('Welcome to our website!')}</h1> ); }
언어 스위처 구현: components/LanguageSwitcher.tsx에서 useTolgee 훅을 사용하여 changeLanguage 및 getLanguage 함수로 간단한 언어 선택 컴포넌트를 만듭니다.
typescript // components/LanguageSwitcher.tsx 'use client'; import { useTolgee } from '@tolgee/react'; export default function LanguageSwitcher() { const { changeLanguage, getLanguage } = useTolgee(); return ( <select value={getLanguage()} onChange={(e) => changeLanguage(e.target.value)} className="border rounded p-2" > <option value="en">English</option> <option value="id">Indonesian</option> </select> ); }