---
title: "Vite 통합"
---

**Lingo.dev 컴파일러**는 Vite와 직접 통합되어 React 애플리케이션에 빌드 타임 현지화를 제공합니다.

Vite + React 애플리케이션에 다국어 지원을 추가하려면 다음 단계를 따르세요.

또는 [Vite 데모 프로젝트](https://github.com/lingodotdev/lingo.dev/tree/main/demo/vite-project)를 살펴보고 컴파일러를 실제로 사용해 보세요.

## 사전 요구사항

- **Vite 4+**
- **React 18+**
- Node.js 18 이상

## 1단계. 패키지 설치

**lingo.dev** 패키지를 설치하세요:

```bash
npm install lingo.dev
```

## 2단계. Vite 구성

컴파일러를 `vite.config.ts`에 가져오고 구성하세요:

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

const viteConfig = {
  plugins: [react()],
  // 기존 Vite 구성
};

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
  })(viteConfig),
);
```

## 3단계. 인증 설정

**Lingo.dev 컴파일러**는 콘텐츠를 AI 번역 엔진으로 전송하여 현지화하므로 먼저 인증이 필요합니다.

### 옵션 1. Lingo.dev 엔진

Lingo.dev 컴파일러는 AI 번역 엔진으로 **Lingo.dev 엔진**을 사용할 수 있습니다. 이는 동적 모델 선택, 자동 라우팅, 번역 메모리 및 용어집 지원을 제공합니다. 무료 및 유료 옵션이 제공됩니다.

인증하려면 다음을 실행하세요:

```bash
npx lingo.dev@latest login
```

브라우저 흐름에 문제가 있는 경우 `.env`에 `LINGODOTDEV_API_KEY`를 수동으로 추가할 수 있습니다:

```bash

# .env

LINGODOTDEV_API_KEY=...
```

Lingo.dev 엔진 프로젝트 설정에서 토큰을 찾을 수 있습니다.

### 옵션 2. 대체 LLM 제공업체

또는 지원되는 LLM 제공업체의 모델을 사용할 수 있습니다:

- [GROQ](https://groq.com/)
- [Google AI](https://aistudio.google.com/)
- [OpenRouter](https://openrouter.ai/)
- [Ollama](https://ollama.com/)

API 키를 `.env`에 추가하세요:

```bash

# .env

GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENROUTER_API_KEY=...
```

**참고:** 컴파일러에서 사용하기 전에 LLM 제공업체에서 계정을 활성화하고 서비스 약관에 동의해야 합니다.

## 4단계. 제공자 추가

메인 진입점 파일(`src/main.tsx`)에 제공자를 가져옵니다:

```tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";
import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
      <App />
    </LingoProviderWrapper>
  </React.StrictMode>,
);
```

## 5단계. 선택 사항: 로케일 전환기 추가

앱 또는 헤더에 언어 전환기 컴포넌트를 생성합니다:

```tsx
import { LocaleSwitcher } from "lingo.dev/react/client";

function App() {
  return (
    <div className="App">
      <header>
        <LocaleSwitcher locales={["en", "es", "fr", "de"]} />
      </header>
      <main>
        <h1>Welcome to our app</h1>
        <p>This content is automatically translated</p>
      </main>
    </div>
  );
}

export default App;
```

## 6단계. 빌드 및 테스트

개발 서버를 시작하세요:

```bash
npm run dev
```

컴파일러는 자동으로 다음을 수행합니다:

1. React 컴포넌트에서 번역 가능한 콘텐츠 스캔
2. 번역 키 추출
3. AI 기반 번역 생성
4. `lingo/` 디렉토리에 최적화된 번역 파일 생성

`http://localhost:5173`에 접속하여 다국어 앱이 작동하는 것을 확인하세요.

## 구성 옵션

컴파일러 동작을 사용자 정의할 수 있습니다:

```ts
export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    sourceLocale: "en",
    targetLocales: ["es", "fr", "de", "ja"],
    lingoDir: "lingo",
    debug: false,
  })(viteConfig),
);
```

## 개발 기능

### 핫 모듈 교체(HMR)

컴파일러는 번역 업데이트를 위한 Vite의 HMR을 지원합니다:

```tsx
// src/components/Welcome.tsx
export function Welcome() {
  return (
    <div>
      <h1>Welcome to our app</h1>
      <p>Edit this text and see translations update automatically</p>
    </div>
  );
}
```

### 빌드 최적화

Vite의 빌드 최적화는 컴파일러와 원활하게 작동합니다:

- **코드 분할**은 번역 번들을 포함합니다
- **자산 최적화**는 번역 파일을 효율적으로 처리합니다
- **트리 쉐이킹**은 사용되지 않는 번역을 제거합니다

## 예제 프로젝트 구조

```
my-vite-app/
├── src/
│   ├── components/
│   │   └── Welcome.tsx
│   ├── App.tsx
│   ├── main.tsx
│   └── lingo/           # 생성된 번역 파일
│       ├── meta.json
│       └── dictionary.js
├── vite.config.ts
├── package.json
└── .env
```

## 프로덕션 배포

1. **애플리케이션 빌드**:

   ```bash
   npm run build
   ```

2. **번역 파일 커밋**:

   ```bash
   git add src/lingo/
   git commit -m "Add translations"
   ```

3. **선호하는 플랫폼(Vercel, Netlify 등)을 사용하여 배포**

Vite 앱은 사용자 환경 설정에 따라 자동으로 현지화된 콘텐츠를 제공합니다.

## 문제 해결

### 일반적인 문제

**번역이 생성되지 않음**: `.env` 파일에 `GROQ_API_KEY`가 올바르게 설정되어 있는지 확인하세요.

**빌드 오류**: `lingo/` 디렉토리가 버전 관리에 포함되어 있는지 확인하세요.

**HMR이 작동하지 않음**: 새로운 번역 가능한 콘텐츠를 추가한 후 개발 서버를 재시작하세요.

## 다음 단계

- **고급 구성**: [커스터마이제이션 옵션](/compiler/configuration/advanced)
- **FAQ**: [일반적인 질문 및 문제 해결](/compiler/guides/faq)
- **작동 방식**: [빌드 프로세스 이해하기](/compiler/how-it-works)
