react-i18next / i18next에서 Intlayer로 마이그레이션하기

왜 react-i18next / i18next에서 Intlayer로 마이그레이션해야 하나요?

마이그레이션 전략

react-i18next / i18next에서 Intlayer로 마이그레이션하기 위한 두 가지 보완적 전략이 있습니다:

1. 호환성 어댑터 (기존 앱에 권장) — @intlayer/react-i18next (React 컴포넌트용) 및/또는 @intlayer/i18next (핵심 i18n 인스턴스용)를 설치하세요. 이러한 패키지들은 react-i18next / i18next와 정확히 동일한 API를 제공하면서 모든 번역 작업을 Intlayer에 위임합니다. useTranslation, Trans, withTranslation, i18next.t()에 대한 기존 호출은 그대로 유지됩니다. 변경 사항은 가져오기 경로뿐입니다.

2. 전체 마이그레이션 — react-i18next API를 점진적으로 기본 Intlayer 훅(useIntlayer, IntlayerProvider)으로 교체하고 컴포넌트와 함께 .content.ts 파일 내에 콘텐츠를 배치합니다.

이 가이드에서는 먼저 전략 1 (쉽게 도입할 수 있는 호환성 어댑터)에 대해 설명하고, 선택 사항인 전체 마이그레이션에 대해 알아봅니다.

목차

빠른 마이그레이션

다음 단계는 코드를 변경하지 않고 기존 react-i18next 앱을 Intlayer에서 실행하기 위해 필요한 최소한의 작업입니다.

1. 1

   의존성 설치

   Intlayer 핵심 패키지와 호환성 어댑터를 설치합니다:

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-pluginnpx intlayer init

   react-i18next와 i18next를 계속 설치해 둘 수 있습니다 — 호환성 어댑터는 TypeScript 타입을 위해 이를 선택적 devDependencies / peerDependencies로 사용합니다. package.json에서 peer 의존성을 변경할 필요가 없습니다.

2. 2

   Intlayer 설정

   intlayer init 명령어는 초기 intlayer.config.ts 파일을 만듭니다. 기존 로케일(언어)과 일치하도록 업데이트하고 syncJSON 플러그인이 메시지 파일을 가리키도록 설정하세요:

   intlayer.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // 기존에 사용하던 모든 로케일을 여기에 추가하세요
       ],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         // react-i18next 플레이스홀더 구문인 {{name}}과 일치시킵니다.
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

   source는 로케일을 해당 JSON 파일 경로로 매핑합니다. location은 Intlayer 관찰자(Watcher)에게 변경 사항을 모니터링할 폴더를 알려줍니다. format: 'i18next' 옵션은 {{name}}과 같은 플레이스홀더가 올바르게 분석되도록 보장합니다.

3. 3

   번들러에 Intlayer 플러그인 추가하기

   기존 번들러 구성을 호환성 플러그인으로 래핑하세요. 이는 핵심 Intlayer 플러그인을 결합하고 콘텐츠 관찰을 연결하며, 가장 중요하게는 모듈 별칭을 주입합니다. 따라서 기존의 import … from 'react-i18next' (및 'i18next') 호출이 빌드 시 자동으로 @intlayer/react-i18next / @intlayer/i18next로 리디렉션됩니다. 소스 코드를 변경할 필요가 없습니다.

   Vite의 경우:

   vite.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";
   import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
   
   export default defineConfig({
     plugins: [react(), reactI18nextVitePlugin()],
   });

   reactI18nextVitePlugin()은 vite-intlayer의 intlayer() 플러그인을 래핑하며, react-i18next / i18next 별칭을 자동으로 추가합니다. 일반적인 vite-intlayer의 intlayer() 플러그인을 사용하면 사전은 컴파일되지만 별칭은 추가되지 않습니다 — 이 경우 수동으로 @intlayer/*를 참조하도록 가져오기 경로를 이름을 변경해야 합니다(단계 4 참고).

   Next.js의 경우:

   next-i18next (Pages Router 통합)를 사용하는 경우 @intlayer/next-i18next와 next-intlayer를 설치하세요:

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npm install @intlayer/next-i18next next-intlayer

   그런 다음 next.config.ts에 호환성 플러그인을 추가합니다 (next-i18next / react-i18next / i18next 별칭이 주입됩니다):

   next.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import type { NextConfig } from "next";
   import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
   
   const withIntlayer = createNextI18nPlugin();
   
   const nextConfig: NextConfig = {
     /* 귀하의 설정 옵션 */
   };
   
   export default withIntlayer(nextConfig);

   i18next.init()나 수동 Provider 부트스트래핑이 더 이상 필요하지 않습니다. Intlayer는 모든 사전을 빌드 시간에 컴파일하므로 런타임에 메시지를 불러오는 단계가 없습니다. 별칭으로 적용된 Provider가 초기화를 담당합니다.

이것으로 빠른 마이그레이션이 완료되었습니다. 이제 앱은 모든 가져오기와 react-i18next API를 그대로 유지한 채 Intlayer에서 작동합니다.

자동화된 타입의 번역 키. Intlayer가 사전을 컴파일하면 useTranslation 및 getFixedT는 실제 콘텐츠에 대해 타입 검사를 수행합니다. 키는 IDE에서 자동 완성되며 유효하지 않은 경로는 빌드 시에 TypeScript 오류로 나타납니다 — 추가 설정이 필요 없습니다.

tsx

콘텐츠 복사

코드 복사

코드를 클립보드에 복사

// 'about'은 등록된 사전 키입니다 → t()는 유효한 경로만 수용합니다.const { t } = useTranslation("about");t("counter.label"); // ✓ 자동 완성t("does.not.exist"); // ✗ TypeScript 오류// 서버 측 (i18next 인스턴스)const tAbout = i18n.getFixedT(null, "about");tAbout("counter.label"); // ✓ 타입 적용됨

전체 마이그레이션

아래 단계는 선택 사항이며 점진적으로 수행할 수 있습니다. 이는 시각적 에디터, CMS, 타입이 있는 콘텐츠 파일, AI 지원 번역 자동화 등 Intlayer의 전체 기능을 열어줍니다.

1. 4

   명시적으로 가져오기 이름 변경 (선택 사항)

   선택사항

   Intlayer 플러그인은 이미 번들러 수준에서 별칭 지정을 처리합니다. 소스 파일에서 명시적으로 의존성을 나타내고 싶다면 수동으로 가져오기 경로를 변경할 수 있습니다:

   테이블의 모든 내용 표시

   테이블의 모든 내용 표시

   테이블을 모달로 열어 모든 데이터를 명확하게 확인

   변경 전	변경 후
   import { useTranslation } from 'react-i18next'	import { useTranslation } from '@intlayer/react-i18next'
   import { Trans } from 'react-i18next'	import { Trans } from '@intlayer/react-i18next'
   import { withTranslation } from 'react-i18next'	import { withTranslation } from '@intlayer/react-i18next'
   import { I18nextProvider } from 'react-i18next'	import { I18nextProvider } from '@intlayer/react-i18next'
   import { initReactI18next } from 'react-i18next'	import { initReactI18next } from '@intlayer/react-i18next'
   import i18next from 'i18next'	import i18next from '@intlayer/i18next'
   import { createInstance } from 'i18next'	import { createInstance } from '@intlayer/i18next'
   import { t } from 'i18next'	import { t } from '@intlayer/i18next'

   Next.js (next-i18next)의 경우:

   테이블의 모든 내용 표시

   테이블의 모든 내용 표시

   테이블을 모달로 열어 모든 데이터를 명확하게 확인

   변경 전	변경 후
   import { serverSideTranslations } from 'next-i18next/serverSideTranslations'	import { serverSideTranslations } from '@intlayer/next-i18next'
   import { appWithTranslation } from 'next-i18next'	import { appWithTranslation } from '@intlayer/next-i18next'
   import { useTranslation } from 'next-i18next'	import { useTranslation } from '@intlayer/next-i18next'

2. 5

   AI 기반 번역 자동화 활성화

   선택사항

   Intlayer 설정이 완료되면, CLI를 사용하여 누락된 번역을 자동으로 채울 수 있습니다:

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   # 누락된 번역 테스트 (CI에 추가)npx intlayer test# AI를 사용하여 누락된 번역 채우기npx intlayer fill

   AI 구성을 intlayer.config.ts에 추가하세요:

   intlayer.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     plugins: [
       syncJSON({
         format: "i18next",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // 기본값
       // model: "gpt-4o-mini",   // 기본값
     },
   };
   
   export default config;

   사용할 수 있는 모든 옵션은 Intlayer CLI 문서에서 확인하세요.

마이그레이션 후 삭제할 수 있는 항목

호환성 어댑터가 제자리에 배치되면 기존에 사용하던 표준 react-i18next / i18next 상용구를 삭제할 수 있습니다:

한 단계 더 나아갈 준비가 되면 Intlayer는 코드베이스 내의 모든 .content.ts 및 .content.json 파일을 자동으로 감지합니다(기본적으로 ./src 내의 어느 곳에서든). MyComponent.tsx 바로 옆에 my-component.content.ts 파일을 추가하기만 하면 Intlayer는 별도 설정 없이 컴파일 타임에 이를 감지합니다 — 가져오기, 등록, 중앙 인덱스 파일이 필요 없습니다. 페이지와 컴포넌트에서 번역의 위치 통일이 매우 매끄러워집니다.

TypeScript 설정

Intlayer는 번역 키에 대해 전체 TypeScript IntelliSense(자동 완성)를 제공하기 위해 모듈 확장을 사용합니다. tsconfig.json 파일에 자동으로 생성된 타입이 포함되어 있는지 확인하세요:

{  // ... 기존 TypeScript 설정  "include": [    // ... 기존 TypeScript 설정    ".intlayer/**/*.ts", // 자동으로 생성된 타입 포함  ],}

Git 설정

Intlayer가 생성한 디렉토리를 .gitignore에 추가하세요:

# Intlayer에서 생성된 파일 무시.intlayer

더 알아보기

• 시각적 에디터 — 브라우저에서 시각적으로 번역을 관리하세요: Intlayer 시각적 에디터
• CMS — 콘텐츠를 외부로 분리하고 원격으로 관리하세요: Intlayer CMS
• VS Code 확장 — 실시간 번역 자동 완성 및 오류 감지를 경험하세요: Intlayer VS Code 확장
• CLI 레퍼런스 — 사용 가능한 CLI 명령어 목록: Intlayer CLI
• Intlayer와 React — React 전체 설정 가이드: intlayerwithvite+react.md
• Intlayer와 Next.js — Next.js 전체 설정 가이드: intlayerwithnextjs_16.md