next-intl에서 Intlayer로 마이그레이션하기

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

마이그레이션 전략

기존 애플리케이션을 위한 추천 접근 방식은 호환성 어댑터를 사용하는 것입니다: @intlayer/next-intl을 설치하세요. 이 어댑터는 next-intl과 정확히 동일한 API를 제공하면서 모든 번역 작업을 백그라운드에서 Intlayer에 위임합니다.

기존에 사용하던 useTranslations, getTranslations, NextIntlClientProvider 및 기타 구성 요소는 계속 유지할 수 있습니다 — 가져오기 경로만 변경하면 됩니다. 함수 호출 방식, 속성 형태, 컴포넌트 구조의 리팩토링이 필요하지 않습니다.

시간이 지남에 따라 점진적으로 개별 파일을 더욱 강력한 Intlayer의 .content.ts 형식으로 옮기면, 시각적 에디터, CMS 및 컴포넌트 레벨의 콘텐츠 스코프를 활용할 수 있습니다 — 하지만 이는 전적으로 선택 사항이며 점진적으로 도입할 수 있습니다.

목차

빠른 마이그레이션

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

1. 1

   의존성 설치

   Intlayer 핵심 패키지와 @intlayer/next-intl 호환성 어댑터를 설치합니다:

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-pluginnpx intlayer init

   next-intl은 계속 설치해 두세요 — URL 라우팅(createNavigation, createMiddleware, Link, redirect, usePathname, useRouter)을 위해 계속 필요합니다. 호환성 어댑터는 라우팅 레이어를 교체하지 않습니다.

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({
         // 'icu'는 next-intl의 ICU 플레이스홀더 구문인 {name}, {count, plural, ...}과 일치시킵니다.
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;

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

   가능한 모든 구성 옵션은 설정 문서를 참조하세요.

3. 3

   Next.js에 Intlayer 플러그인 통합

   기존 Next.js 설정을 @intlayer/next-intl/plugin의 createNextIntlPlugin으로 래핑하세요. 이 래퍼는 withIntlayer를 결합하면서 동시에 next-intl → @intlayer/next-intl 별칭을 등록합니다:

   next.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {
     /* 기존 설정 옵션들 */
   };
   
   export default withIntlayer(nextConfig);

   createNextIntlPlugin()은 withIntlayer를 래핑하여 Webpack이나 Turbopack을 자동으로 감지하고, 콘텐츠 감시와 사전 컴파일을 연결하며 가장 중요하게는 모듈 별칭을 주입합니다. 이를 통해 기존의 import … from 'next-intl'에 대한 호출이 빌드 시간에 투명하게 @intlayer/next-intl로 리디렉션됩니다. 라우팅 관련 파일인 next-intl/routing 항목은 여전히 실제 패키지를 가리킵니다. 소스 코드를 변경할 필요가 없습니다.

   순수한 next-intlayer/server의 withIntlayer를 사용하고 싶나요? 이 경우 사전은 컴파일되지만 next-intl에 대한 별칭은 추가되지 않습니다 — 따라서 수동으로 @intlayer/next-intl을 참조하도록 가져오기 경로를 이름을 변경해야 합니다(단계 4 참고).

   getRequestConfig나 loadMessages 파일은 더 이상 필요하지 않습니다. next-intl을 사용할 때는 모든 요청마다 getRequestConfig를 통해 JSON 메시지 번들을 불러오기 위해 src/i18n.ts 파일을 작성해야 했습니다. Intlayer는 모든 사전을 빌드 시간에 컴파일하므로 런타임에 메시지를 불러오는 단계가 없습니다. 이 파일을 완전히 지우셔도 됩니다 (계속해서 createNavigation을 사용한다면 라우팅 관련 코드만 남기세요).

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

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

tsx

콘텐츠 복사

코드 복사

코드를 클립보드에 복사

// 클라이언트 컴포넌트 — 'about'은 등록된 사전 키입니다.const t = useTranslations("about");t("counter.label"); // ✓ 자동 완성t("does.not.exist"); // ✗ TypeScript 오류// 서버 컴포넌트const t = await getTranslations("about");t("counter.label"); // ✓ 타입 적용됨

전체 마이그레이션

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

1. 4

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

   선택사항

   createNextIntlPlugin() 래퍼는 이미 번들러 수준에서 next-intl → @intlayer/next-intl 별칭 처리를 관리합니다. 소스 파일에서 의존성을 명확히 하고 싶거나, 단순한 withIntlayer 플러그인을 직접 사용하려는 경우 가져오기 경로를 수동으로 변경할 수 있습니다:

   테이블의 모든 내용 표시

   테이블의 모든 내용 표시

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

   변경 전	변경 후
   import { useTranslations } from 'next-intl'	import { useTranslations } from '@intlayer/next-intl'
   import { useLocale } from 'next-intl'	import { useLocale } from '@intlayer/next-intl'
   import { NextIntlClientProvider } from 'next-intl'	import { NextIntlClientProvider } from '@intlayer/next-intl'
   import { getTranslations } from 'next-intl/server'	import { getTranslations } from '@intlayer/next-intl/server'
   import { getLocale } from 'next-intl/server'	import { getLocale } from '@intlayer/next-intl/server'
   import { setLocale } from 'next-intl/server'	import { setLocale } from '@intlayer/next-intl/server'
   import { getMessages } from 'next-intl/server'	import { getMessages } from '@intlayer/next-intl/server'

   실제 next-intl에서 제공하는 라우팅 가져오기는 항상 유지하세요 — 호환성 어댑터는 URL 라우팅 레이어를 대체하지 않습니다:

   ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   // ✅ 이 항목들은 항상 실제 'next-intl'에서 불러옵니다.import { createNavigation } from "next-intl/routing";import { createMiddleware } from "next-intl/server";import { defineRouting } from "next-intl/routing";

   혹은 @intlayer/next-intl/routing의 defineRouting을 사용하면 intlayer.config.ts 파일의 로케일 설정을 자동으로 병합할 수 있습니다.

2. 5

   AI 기반 번역 자동화 활성화

   선택사항

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

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

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

   .env 파일에 OPENAI_API_KEY(또는 선호하는 제공 업체의 키)를 추가하고, 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: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // 기본값
       // model: "gpt-4o-mini",   // 기본값
     },
   };
   
   export default config;

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

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

@intlayer/next-intl이 적용되면, 다음의 기존 next-intl 표준 상용구를 삭제할 수 있습니다:

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