@nuxtjs/i18n에서 Intlayer로 마이그레이션하기

왜 @nuxtjs/i18n에서 Intlayer로 마이그레이션해야 하나요?

마이그레이션 전략

@nuxtjs/i18n은 내부적으로 vue-i18n에 의해 작동하므로, Intlayer로 마이그레이션하기 위한 두 가지 보완적 전략이 있습니다:

1. 호환성 어댑터 (기존 앱에 권장) — @intlayer/vue-i18n과 nuxt-intlayer를 설치하세요. 이 기능은 vue-i18n과 정확히 동일한 API를 노출하지만, 모든 번역 작업을 Intlayer에 위임합니다. $t, useI18n() 및 Nuxt 라우팅에 대한 기존 호출은 그대로 유지됩니다. 변경 사항은 초기화뿐입니다.

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

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

목차

빠른 마이그레이션

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

1. 1

   의존성 설치

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

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npm install intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-pluginnpx intlayer init

   조만간 Nuxt 설정에서 @nuxtjs/i18n을 제거하겠지만 마이그레이션하는 동안 안전하게 설치해 둘 수 있습니다.

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

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

3. 3

   Nuxt 설정 업데이트

   nuxt.config.ts에서 @nuxtjs/i18n 모듈을 nuxt-intlayer로 교체하세요. Intlayer 플러그인이 모듈 별칭을 자동으로 주입하므로, 기존의 import { useI18n } from 'vue-i18n' 호출이 부드럽게 @intlayer/vue-i18n으로 리디렉션됩니다.

   nuxt.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   export default defineNuxtConfig({
     // '@nuxtjs/i18n' 삭제
     modules: ["nuxt-intlayer"],
   });

   더 이상 Nuxt i18n 구성 객체를 정의할 필요가 없습니다. Intlayer는 모든 사전을 빌드 시간에 컴파일하고, 로케일 감지, 라우팅 및 사전 불러오기를 매끄럽게 처리합니다.

이것으로 빠른 마이그레이션이 완료되었습니다. 이제 Nuxt 앱은 모든 $t 호출 및 useI18n()을 그대로 유지한 채 Intlayer에서 작동합니다.

전체 마이그레이션

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

1. 4

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

   선택사항

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

   테이블의 모든 내용 표시

   테이블의 모든 내용 표시

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

   변경 전	변경 후
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'

   이는 드롭인 교체(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: "icu",
         source: ({ locale }) => `./locales/${locale}.json`,
         location: "locales",
       }),
     ],
     ai: {
       apiKey: process.env.OPENAI_API_KEY,
       // provider: "openai",     // 기본값
       // model: "gpt-4o-mini",   // 기본값
     },
   };
   
   export default config;

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

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

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

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