마이그레이션 가이드

알파

Lingo.dev Compiler는 알파 버전입니다. 아직 안정적이지 않으며 프로덕션 환경에서의 사용은 권장되지 않습니다. 또한 릴리스마다 API가 변경될 수 있습니다.

이 가이드는 기존 lingo.dev compiler 패키지에서 현재의 @lingo.dev/compiler 패키지로 마이그레이션하는 방법을 설명합니다. 새 패키지에는 scoped npm 이름, 간소화된 API, plugin 기반 Vite 통합, 그리고 메타데이터를 위한 새로운 .lingo/ 디렉터리가 도입되었습니다.

변경 사항 요약#

항목	이전 (`lingo.dev`)	이후 (`@lingo.dev/compiler`)
패키지 이름	`lingo.dev`	`@lingo.dev/compiler`
Next.js 통합	config 직접 수정	`withLingo()` 비동기 래퍼
Vite 통합	수동 설정	`lingoCompilerPlugin`
LingoProvider	`loadDictionary` prop 필수	prop 불필요
메타데이터 디렉터리	`lingo/`	`.lingo/`
옵트인 directive	`'use i18n'` 필수	선택 사항(기본값: 모두 번역)
import	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

단계별 마이그레이션#

패키지 교체

기존 패키지를 제거한 뒤 새 패키지를 설치하세요:

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

import 업데이트

모든 import 경로를 교체하세요:

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";

Next.js config 업데이트(해당하는 경우)

이제 Next.js config는 비동기 함수여야 합니다:

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
  });
}

비동기 함수 래퍼는 필수입니다. 동기 export를 사용하면 빌드가 실패합니다. 자세한 내용은 Next.js Integration을 참고하세요.

Vite config 업데이트(해당하는 경우)

수동 설정이 있다면 lingoCompilerPlugin으로 교체하세요:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

LingoProvider 간소화

이제 loadDictionary prop은 더 이상 필요하지 않습니다. Compiler가 사전 로딩을 자동으로 처리합니다:

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

// After
import { LingoProvider } from "@lingo.dev/compiler/react";

<LingoProvider>
  <App />
</LingoProvider>

메타데이터 디렉터리 이동

메타데이터 디렉터리 이름을 lingo/에서 .lingo/로 변경하세요:

bash

mv lingo/ .lingo/

이전 디렉터리 이름을 참조하고 있다면 .gitignore도 함께 업데이트하세요. .lingo/ 디렉터리는 버전 관리에 커밋해야 합니다.

'use i18n' directive 업데이트(선택 사항)

새 패키지에서는 'use i18n'이 선택 사항입니다. 기본적으로 sourceRoot 안의 모든 파일이 번역됩니다. 옵트인 동작을 유지하려면 config에서 useDirective: true을 설정하세요:

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

useDirective을 제거했거나(false로 설정한 경우 포함) 파일에 있는 'use i18n' directive도 제거할 수 있습니다. sourceRoot 안의 모든 파일이 자동으로 번역됩니다.

리빌드 및 확인

dev server를 실행한 뒤 번역이 제대로 표시되는지 확인하세요:

bash

npm run dev

다음을 확인하세요:

pseudotranslator가 [!!! ... !!!] 마커를 생성하는지(활성화된 경우)
이전에 번역된 모든 문자열이 계속 정상적으로 동작하는지
.lingo/metadata.json 파일이 생성되었거나 업데이트되었는지

다음 단계#

이 페이지가 도움이 되었나요?

마이그레이션 가이드

알파

변경 사항 요약#

항목	이전 (`lingo.dev`)	이후 (`@lingo.dev/compiler`)
패키지 이름	`lingo.dev`	`@lingo.dev/compiler`
Next.js 통합	config 직접 수정	`withLingo()` 비동기 래퍼
Vite 통합	수동 설정	`lingoCompilerPlugin`
LingoProvider	`loadDictionary` prop 필수	prop 불필요
메타데이터 디렉터리	`lingo/`	`.lingo/`
옵트인 directive	`'use i18n'` 필수	선택 사항(기본값: 모두 번역)
import	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

단계별 마이그레이션#

패키지 교체

기존 패키지를 제거한 뒤 새 패키지를 설치하세요:

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

import 업데이트

모든 import 경로를 교체하세요:

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";

Next.js config 업데이트(해당하는 경우)

이제 Next.js config는 비동기 함수여야 합니다:

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
  });
}

비동기 함수 래퍼는 필수입니다. 동기 export를 사용하면 빌드가 실패합니다. 자세한 내용은 Next.js Integration을 참고하세요.

Vite config 업데이트(해당하는 경우)

수동 설정이 있다면 lingoCompilerPlugin으로 교체하세요:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

LingoProvider 간소화

이제 loadDictionary prop은 더 이상 필요하지 않습니다. Compiler가 사전 로딩을 자동으로 처리합니다:

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

// After
import { LingoProvider } from "@lingo.dev/compiler/react";

<LingoProvider>
  <App />
</LingoProvider>

메타데이터 디렉터리 이동

메타데이터 디렉터리 이름을 lingo/에서 .lingo/로 변경하세요:

bash

mv lingo/ .lingo/

이전 디렉터리 이름을 참조하고 있다면 .gitignore도 함께 업데이트하세요. .lingo/ 디렉터리는 버전 관리에 커밋해야 합니다.

'use i18n' directive 업데이트(선택 사항)

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

리빌드 및 확인

dev server를 실행한 뒤 번역이 제대로 표시되는지 확인하세요:

bash

npm run dev

다음을 확인하세요:

pseudotranslator가 [!!! ... !!!] 마커를 생성하는지(활성화된 경우)
이전에 번역된 모든 문자열이 계속 정상적으로 동작하는지
.lingo/metadata.json 파일이 생성되었거나 업데이트되었는지

다음 단계#

이 페이지가 도움이 되었나요?