빠른 시작
5분 이내에 React 앱에 다국어 지원을 추가하세요.
사전 요구사항
- Node.js 18+
- Next.js(App Router) 또는 Vite를 사용하는 React 애플리케이션
설치
pnpm install @lingo.dev/compiler
구성
Next.js
설정을 비동기로 만들고 withLingo로 래핑하세요:
// next.config.ts
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",
dev: {
usePseudotranslator: true, // Fake translations for development
},
});
}
Vite
Vite 설정에 Lingo 플러그인을 추가하세요:
// vite.config.ts
import { defineConfig } from "vite";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";
export default defineConfig({
plugins: [
lingoCompilerPlugin({
sourceRoot: "src",
sourceLocale: "en",
targetLocales: ["es", "de", "fr"],
models: "lingo.dev",
dev: {
usePseudotranslator: true,
},
}),
// ...other plugins
],
});
프로바이더 설정
Next.js
루트 레이아웃에서 LingoProvider로 앱을 래핑하세요:
// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<LingoProvider>
<html>
<body>{children}</body>
</html>
</LingoProvider>
);
}
Vite
진입점에서 LingoProvider로 앱을 래핑하세요:
// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<LingoProvider>
<App />
</LingoProvider>
</StrictMode>
);
인증
컴파일러는 기본적으로 번역에 Lingo.dev 엔진을 사용합니다.
옵션 1: Lingo.dev 엔진 (권장)
lingo.dev에서 가입하고 인증하세요:
npx lingo.dev@latest login
Windows 사용자:
npx lingo.dev가 환경에서 실행되지 않는 경우:
- 패키지를 설치하세요:
npm install lingo.dev@latest- 대신
npx lingo를 사용하세요 (예:npx lingo login)
API 키가 로컬에 저장됩니다. 무료 Hobby 티어는 대부분의 프로젝트에 충분합니다.
인증 문제가 있나요? 브라우저가 인증 플로우를 차단하는 경우 .env에 API 키를 수동으로 추가하세요:
LINGODOTDEV_API_KEY=your_key_here
Lingo.dev 프로젝트 설정에서 API 키를 찾을 수 있습니다.
옵션 2: 직접 LLM 제공자 사용
또는 지원되는 LLM 제공자를 직접 사용할 수 있습니다. 설정을 업데이트하세요:
{
models: {
"*:*": "groq:llama-3.3-70b-versatile",
// or "google:gemini-2.0-flash"
// or "openai:gpt-4o"
// or "anthropic:claude-3-5-sonnet"
}
}
해당 API 키를 .env에 추가하세요:
GROQ_API_KEY=your_key
# or GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY
지원되는 모든 제공자는 번역 제공자를 참조하세요.
개발 서버 실행
개발 서버를 시작하세요:
npm run dev
컴파일러는 다음을 수행합니다:
- JSX에서 번역 가능한 텍스트 스캔
- 의사 번역 생성(번역되는 내용을 시각화하기 위한 가짜 번역)
- 컴포넌트에 주입
.lingo/metadata.json에 메타데이터 저장
의사 번역을 사용하는 이유는? 즉시 생성되고(API 호출 없음), 번역되는 내용을 정확히 보여주며, 다양한 텍스트 길이로 UI를 테스트할 수 있습니다. 모두 API 크레딧을 사용하지 않고 가능합니다.
번역 테스트
간단한 컴포넌트를 추가하세요:
export function Welcome() {
return (
<div>
<h1>Welcome to our app</h1>
<p>This text will be translated automatically</p>
</div>
);
}
코드 변경이 필요 없습니다. 텍스트가 자동으로 추출되고 번역됩니다.
언어 전환기 추가(선택 사항)
사용자가 언어를 변경할 수 있도록 하세요:
"use client"; // For Next.js
import { useLingoContext } from "@lingo.dev/compiler/react";
export function LanguageSwitcher() {
const { locale, setLocale } = useLingoContext();
return (
<select value={locale} onChange={(e) => setLocale(e.target.value)}>
<option value="en">English</option>
<option value="es">Español</option>
<option value="de">Deutsch</option>
<option value="fr">Français</option>
</select>
);
}
실제 번역 생성
실제 번역을 사용할 준비가 되면 설정을 업데이트하세요:
{
dev: {
usePseudotranslator: false, // Disable fake translations
}
}
개발 서버를 재시작하세요. 이제 컴파일러가 새로 추가되거나 변경된 텍스트에 대해 실제 AI 번역을 생성합니다.
비용이 걱정되시나요? 의사 번역은 무료이며 즉시 생성됩니다. 실제 번역 품질을 검토해야 할 때만 비활성화하세요.
자주 묻는 질문
번역 가능한 모든 문자열을 표시해야 하나요?
아니요. 컴파일러가 JSX 텍스트를 자동으로 감지합니다. 대신 옵트인 방식을 사용하려면 useDirective: true를 설정하고 번역하려는 파일 상단에 'use i18n'를 추가하세요.
동적 콘텐츠나 props는 어떻게 하나요?
컴파일러는 alt, aria-label, placeholder와 같은 문자열 속성을 자동으로 처리합니다. 동적 텍스트의 경우 템플릿 구문을 사용하세요: <p>Hello {name}</p>는 예상대로 작동합니다.
특정 번역을 사용자 정의할 수 있나요?
예. data-lingo-override 속성을 사용하세요:
<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
Welcome
</h1>
번역을 어떻게 커밋하나요?
.lingo/ 디렉토리를 버전 관리에 커밋하세요. 여기에는 메타데이터와 캐시된 번역이 포함되어 있으며, 커밋해도 안전하고 코드와 함께 버전 관리되어야 합니다.