vue-i18n에서 Intlayer로 마이그레이션하기

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

마이그레이션 전략

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

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

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

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

목차

빠른 마이그레이션

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

1. 1

   의존성 설치

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

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

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

   vue-i18n을 계속 설치해 둘 수 있습니다 — 호환성 어댑터는 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({
         // vue-i18n 플레이스홀더 구문인 {name}과 일치시킵니다.
         format: "icu",
         source: ({ locale }) => `./src/locales/${locale}.json`,
         location: "src/locales",
       }),
     ],
   };
   
   export default config;

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

3. 3

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

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

   Vite의 경우:

   vite.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   import { defineConfig } from "vite";
   import vue from "@vitejs/plugin-vue";
   import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
   
   export default defineConfig({
     plugins: [vue(), vueI18nVitePlugin()],
   });

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

   Nuxt의 경우:

   @nuxtjs/i18n (Nuxt 통합)를 사용하는 경우 nuxt-intlayer를 설치하고 nuxt.config.ts에 추가하세요:

   bash

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   npm install nuxt-intlayer

   nuxt.config.ts

   콘텐츠 복사

   코드 복사

   코드를 클립보드에 복사

   export default defineNuxtConfig({
     modules: ["nuxt-intlayer"],
     // @nuxtjs/i18n 모듈은 안전하게 제거할 수 있습니다
   });

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

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

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

ts

콘텐츠 복사

코드 복사

코드를 클립보드에 복사

// 'about'은 등록된 사전 키입니다.const { t } = useI18n({ namespace: "about" });t("counter.label"); // ✓ 자동 완성t("does.not.exist"); // ✗ TypeScript 오류

전체 마이그레이션

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

1. 4

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

   선택사항

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

   테이블의 모든 내용 표시

   테이블의 모든 내용 표시

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

   변경 전	변경 후
   import { useI18n } from 'vue-i18n'	import { useI18n } from '@intlayer/vue-i18n'
   import { createI18n } from 'vue-i18n'	import { createI18n } 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 }) => `./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 문서에서 확인하세요.

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

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

한 단계 더 나아갈 준비가 되면 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와 Vue — Vue 전체 설정 가이드: intlayerwithvite+vue.md
• Intlayer와 Nuxt — Nuxt 전체 설정 가이드: intlayerwithnuxt.md