빠른 시작 - Lingo.dev Compiler

Lingo.dev 컴파일러는 기존 React 컴포넌트를 변경하지 않고도 빌드 시점에 모든 React 앱을 다국어로 만들 수 있도록 설계되었습니다.

이 빠른 시작 가이드는 5분 이내에 React 앱에 다국어 지원을 추가하는 데 도움이 될 것입니다.

이 가이드를 완료하면 다음과 같은 결과를 얻게 됩니다:

React 앱에 Lingo.dev 컴파일러 설치 및 구성
자동화된 번역 추출 및 주입 설정
최적화된 번역이 포함된 작동하는 다국어 앱

시작해 보겠습니다!

사전 요구 사항

Lingo.dev 컴파일러는 현대적인 React 프레임워크와 함께 작동합니다. 시작하기 전에 다음 지원되는 설정 중 하나가 있는지 확인하세요:

Next.js (App Router)
React Router / Remix
Vite + React

또는 데모 앱을 살펴보세요: Next.js, React Router, Vite.

1단계. 패키지 설치

프로젝트에 lingo.dev 패키지를 설치하세요:

npm install lingo.dev

2단계. 프레임워크 구성

프레임워크를 선택하고 특정 설정을 따르세요:

Next.js

다음과 같이 next.config.js를 업데이트하세요:

import lingoCompiler from "lingo.dev/compiler";

export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  models: "lingo.dev", // 옵션 1: Lingo.dev 엔진
  // models: {
  //   "*:*": "groq:mistral-saba-24b", // 옵션 2: GROQ
  //   "*:*": "google:gemini-2.0-flash", // 옵션 2: Google AI
  //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // 옵션 2: OpenRouter
  //   "*:*": "ollama:mistral-small3.1", // 옵션 2: Ollama
  //   "*:*": "mistral:mistral-small-latest", // Mistral
  // },
})(nextConfig);

React Router / Remix

다음과 같이 vite.config.ts를 업데이트하세요:

import lingoCompiler from "lingo.dev/compiler";

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
    models: "lingo.dev", // 옵션 1: Lingo.dev 엔진
    // models: {
    //   "*:*": "groq:mistral-saba-24b", // 옵션 2: GROQ
    //   "*:*": "google:gemini-2.0-flash", // 옵션 2: Google AI
    //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // 옵션 2: OpenRouter
    //   "*:*": "ollama:mistral-small3.1", // 옵션 2: Ollama
    // },
  })(viteConfig),
);

Vite

다음과 같이 vite.config.ts를 업데이트하세요:

import lingoCompiler from "lingo.dev/compiler";

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
    models: "lingo.dev", // 옵션 1: Lingo.dev 엔진
    // models: {
    //   "*:*": "groq:mistral-saba-24b", // 옵션 2: GROQ
    //   "*:*": "google:gemini-2.0-flash", // 옵션 2: Google AI
    //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // 옵션 2: OpenRouter
    //   "*:*": "ollama:mistral-small3.1", // 옵션 2: Ollama
    //   "*:*": "mistral:mistral-small-latest", // Mistral
    // },
  })(viteConfig),
);

3단계. 인증 설정

Lingo.dev 컴파일러는 로컬라이제이션을 위해 콘텐츠를 AI 번역 엔진으로 전송하므로, 먼저 인증이 필요합니다.

옵션 1. Lingo.dev 엔진

Lingo.dev 컴파일러는 AI 번역 엔진으로 Lingo.dev 엔진을 사용할 수 있습니다.

이는 동적 모델 선택, 각 언어 쌍에 대한 다양한 모델로의 자동 라우팅, 자동화된 모델 폴백, 이전 번역을 고려하는 번역 메모리, 그리고 프로젝트의 도메인별 용어를 위한 용어집 지원을 제공합니다. 무료 및 유료 옵션이 모두 있으며, 무료 Hobby 티어는 대부분의 프로젝트에 충분할 것입니다.

인증을 위해 다음을 실행하세요:

npx lingo.dev@latest login

중요 세부사항. Brave 브라우저를 사용하거나 브라우저 확장 프로그램이 인증 흐름을 차단하는 경우, .env 파일에 LINGODOTDEV_API_KEY 환경 변수를 추가하여 수동으로 인증할 수 있습니다:

LINGODOTDEV_API_KEY=...

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

옵션 2. 대체 LLM 제공업체

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

구성한 LLM 제공업체의 API 키를 환경에 추가하세요:


# .env

GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENROUTER_API_KEY=...
MISTRAL_API_KEY=...

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

4단계. Provider 추가하기

앱을 LingoProvider로 감싸서 번역 기능을 활성화하세요:

Next.js

layout.tsx에서:

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function Layout({ children }) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

React Router / Remix

root.tsx에서:

import { LingoProvider } from "lingo.dev/react/client";
import { loadDictionary } from "lingo.dev/react/react-router";

export async function loader(args) {
  return { lingoDictionary: await loadDictionary(args.request) };
}

export default function Root() {
  const { lingoDictionary } = useLoaderData();
  return (
    <LingoProvider dictionary={lingoDictionary}>
      <html>
        <body>
          <Outlet />
        </body>
      </html>
    </LingoProvider>
  );
}

Vite

main.tsx에서:

import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

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

5단계. 빌드 및 테스트

개발 서버를 실행하세요:

npm run dev

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

React 컴포넌트에서 번역 가능한 텍스트 스캔
번역 키 추출
AI를 사용하여 번역 생성
lingo/ 디렉토리에 최적화된 번역 파일 생성

이제 앱이 다국어를 지원합니다! 컴파일러는 콘텐츠 변경 사항을 추적하는 버전 관리된 사전을 생성하고 수정된 콘텐츠만 재번역합니다.

선택 사항: 언어 전환기 추가

사용자가 언어를 변경할 수 있도록 언어 전환기를 추가하세요:

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

export function Header() {
  return (
    <header>
      <LocaleSwitcher locales={["en", "es", "fr", "de"]} />
    </header>
  );
}

다음 단계

프레임워크별 가이드: Next.js, React Router, Vite
작동 원리: 빌드 타임 처리 이해하기
고급 설정: 커스터마이징 옵션