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

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

마이그레이션 전략

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

1. 호환성 어댑터 (기존 앱에 권장) — @intlayer/i18next를 설치하세요. 이 패키지는 i18next와 정확히 동일한 API를 제공하면서 모든 번역 작업을 Intlayer에 위임합니다. i18next.t(), i18next.changeLanguage() 및 createInstance()에 대한 기존 호출은 그대로 유지됩니다. 변경 사항은 가져오기 경로와 초기화뿐입니다.

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

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

목차

빠른 마이그레이션

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

1. 1

   의존성 설치

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

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npx intlayer init --interactive
   

   --interactive 플래그는 선택 사항입니다. AI 에이전트인 경우 intlayer-cli init를 사용하세요.

   이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npm install intlayer @intlayer/i18next @intlayer/sync-json-plugin
   

   i18next를 계속 설치해 둘 수 있습니다 — 호환성 어댑터는 TypeScript 타입을 위해 이를 devDependency / peerDependency로 사용합니다.

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({
         // 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

   번들러 별칭 업데이트 (선택 사항)

   번들러(Vite, Webpack, esbuild)를 사용하는 경우 모듈 별칭을 삽입하여 import ... from 'i18next'가 자동으로 @intlayer/i18next로 확인되게 할 수 있습니다. 이를 통해 코드베이스 전체에서 가져오기 경로를 수동으로 변경하지 않아도 됩니다.

   Vite의 경우:

   vite.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

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

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

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

전체 마이그레이션

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

1. 4

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

   선택사항

   소스 파일에서 명시적으로 의존성을 나타내고 싶거나, 가져오기를 별칭 지정하는 번들러 플러그인을 사용하지 않는다면 수동으로 가져오기 경로를 변경할 수 있습니다:

   테이블의 모든 내용 표시

   테이블의 모든 내용 표시

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

   변경 전	변경 후
   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'

   이는 드롭인 교체(Drop-in replacements)이므로 함수 호출 시그니처, 매개변수, 반환 타입을 변경할 필요가 없습니다.

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 문서에서 확인하세요.

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

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

한 단계 더 나아갈 준비가 되면 Intlayer는 코드베이스 내의 모든 .content.ts 및 .content.json 파일을 자동으로 감지합니다(기본적으로 ./src 내의 어느 곳에서든). 로직 파일 바로 옆에 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