Bolt

Bolt는 StackBlitz에서 제공하는 AI 기반 브라우저 개발 플랫폼입니다. 이 가이드는 Bolt에서 Lingo.dev Compiler를 사용하여 React 기반 앱을 현지화하는 방법을 설명합니다.

알려진 제한사항

Bolt는 브라우저 내에서 웹 앱을 실행하기 위해 웹 컨테이너를 사용합니다. 이는 강력한 기술이지만, Lingo.dev와 함께 사용할 때 몇 가지 호환성 문제가 있습니다:

Lingo.dev Engine에 인증하기 위해 CLI의 login 명령어가 아닌 API 키만 사용할 수 있습니다.
Bolt에서 Lingo.dev Compiler는 Vite 기반 앱에서만 호환됩니다. Next.js는 사용할 수 없습니다.
<LocaleSwitcher /> 컴포넌트는 Bolt의 내장된 Preview 창에서 작동하지 않습니다.
Ollama는 로컬에서 실행되어야 하므로 Bolt에서 지원되지 않습니다.

1단계. API 키 얻기

Lingo.dev Compiler는 AI로 앱을 현지화하기 위해 대규모 언어 모델(LLM)을 사용합니다. 이러한 모델 중 하나를 사용하려면 지원되는 제공업체 중 하나에서 API 키가 필요합니다. Lingo.dev Engine 또는 커스텀 LLM 제공업체를 사용할 수 있습니다.

Lingo.dev Engine

Lingo.dev Engine은 동적 모델 선택, 자동 라우팅, 번역 메모리 및 용어집 지원을 제공하는 자체 호스팅 플랫폼입니다. 등록은 무료이며 모든 사용자는 매월 10,000 토큰의 무료 사용량을 제공받습니다.

API 키를 얻으려면:

Lingo.dev Engine에 로그인하세요.
Projects 페이지로 이동하세요.
API key > Copy를 클릭하세요.

커스텀 LLM 제공업체

Lingo.dev Compiler는 다음을 포함한 다양한 타사 제공업체와도 통합됩니다:

Google AI
GROQ
Mistral
Ollama (Bolt에서는 지원되지 않음)
OpenRouter

API 키 설정을 위한 정확한 지침은 제공업체에 따라 다릅니다.

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

2단계. lingo.dev 설치

lingo.dev 패키지에는 컴파일러가 포함되어 있습니다.

패키지를 설치하려면:

Bolt에서 프로젝트를 생성하거나 엽니다.
Code 탭으로 전환합니다.
Terminal을 클릭합니다.
다음 명령어를 실행합니다:
```
npm install lingo.dev
```

3단계. Vite 구성

Vite를 사용할 때, Lingo.dev Compiler는 프로젝트의 구성 파일에서 초기화되어야 합니다:

TypeScript를 사용하는 경우, 구성 파일은 vite.config.ts입니다.
JavaScript를 사용하는 경우, 구성 파일은 vite.config.js입니다.

초기화 과정에서 컴파일러의 동작을 구성할 수 있습니다. 이 구성은 번역할 로케일과 현지화에 사용할 모델을 결정합니다.

사용 가능한 옵션의 전체 목록은 컴파일러 옵션을 참조하세요.

Lingo.dev 엔진

Lingo.dev 엔진을 사용하는 경우, models를 "lingo.dev"로 설정하세요:

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

const viteConfig = {
  plugins: [react()],
};

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    lingoDir: "lingo",
    sourceLocale: "en",
    targetLocales: ["es"],
    rsc: false,
    useDirective: false,
    debug: false,
    models: "lingo.dev",
  })(viteConfig),
);

커스텀 LLM 제공자

커스텀 LLM 제공자를 사용하는 경우, models를 소스 및 대상 로케일과 이를 현지화할 모델을 매핑하는 객체로 설정하세요. 예를 들어, 다음 구성은 모든 문자열을 "groq:mistral-saba-24b"로 현지화합니다:

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

const viteConfig = {
  plugins: [react()],
};

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    lingoDir: "lingo",
    sourceLocale: "en",
    targetLocales: ["es"],
    rsc: false,
    useDirective: false,
    debug: false,
    models: {
      "*:*": "groq:mistral-saba-24b",
    },
  })(viteConfig),
);

4단계. 환경 변수 설정

Lingo.dev Compiler가 구성된 모델의 API 키에 접근할 수 있도록 하려면, API 키가 환경 변수로 제공되어야 합니다.

Bolt에서 환경 변수를 설정하는 방법:

.env 파일을 생성합니다.
1. 파일 패널에서 마우스 오른쪽 버튼을 클릭합니다.
2. New file을 선택합니다.
3. .env를 입력합니다.

파일에 관련 환경 변수를 추가합니다:

# Lingo.dev Engine
LINGODOTDEV_API_KEY="YOUR_API_KEY_GOES_HERE"

# Google AI
GOOGLE_API_KEY="YOUR_API_KEY_GOES_HERE"

# GROQ
GROQ_API_KEY="YOUR_API_KEY_GOES_HERE"

# Mistral
MISTRAL_API_KEY="YOUR_API_KEY_GOES_HERE"

# OpenRouter
OPENROUTER_API_KEY="YOUR_API_KEY_GOES_HERE"

참고: Bolt는 자동으로 환경 변수를 암호화합니다. 자세한 내용은 환경 변수 (developer.stackblitz.com)를 참조하세요.

4단계. 프로바이더 추가

lingo.dev 패키지는 <LingoProviderWrapper /> 컴포넌트를 내보냅니다. 이 컴포넌트는 번역을 로드하고 앱 전체에서 사용할 수 있도록 하는 역할을 담당합니다.

이 컴포넌트를 사용하려면 src/main.tsx 파일에 가져와서 <App /> 컴포넌트를 감싸주세요:

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단계. 로케일 전환기 추가

lingo.dev 패키지는 스타일이 적용되지 않은 <LocaleSwitcher /> 컴포넌트를 제공합니다. 이 컴포넌트는 사용자가 선호하는 언어를 설정할 수 있는 드롭다운을 렌더링하고, 재방문 시 해당 선택을 기억합니다.

이 컴포넌트를 사용하려면 <LingoProviderWrapper /> 컴포넌트의 하위 요소로 포함시키고 locales 속성을 소스 및 대상 로케일을 포함하는 배열로 설정합니다:

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

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

export default App;

경고: <LocaleSwitcher /> 컴포넌트는 Bolt의 내장된 미리보기 창에서 작동하지 않습니다. 컴포넌트가 작동하는 것을 보려면 별도 탭에서 미리보기 열기 아이콘을 클릭하세요.

6단계. 빌드 및 테스트

개발 서버가 아직 실행되고 있지 않다면, 다음 명령어로 시작하세요:

npm run dev

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

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