알파
Lingo.dev Compiler는 현재 알파 버전입니다. 안정적이지 않으며 프로덕션 사용은 권장되지 않고, 릴리스마다 API가 변경될 수 있습니다.
Lingo.dev Compiler 구성 객체는 React 애플리케이션을 빌드 시점에 어떻게 번역할지 제어합니다. 이 페이지에서는 사용 가능한 모든 옵션을 타입, 기본값, 사용 예제와 함께 정리해 설명합니다.
핵심 옵션#
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
sourceRoot | string | "src" | 번역 가능한 컴포넌트가 들어 있는 디렉터리입니다. 프로젝트 루트를 기준으로 한 상대 경로입니다. |
lingoDir | string | ".lingo" | 번역 메타데이터와 캐시 파일을 저장하는 디렉터리입니다. |
sourceLocale | string | 필수 | 원본 콘텐츠의 언어 코드입니다(예: "en"). |
targetLocales | string[] | 필수 | 대상 언어 코드 배열입니다(예: ["es", "de", "fr"]). |
useDirective | boolean | false | true이면 'use i18n' 지시어가 있는 파일만 번역됩니다. false이면 sourceRoot 아래의 모든 파일이 번역됩니다. |
models | string | object | "lingo.dev" | 번역 제공자 구성입니다. 문자열을 사용하면 모든 로캘 쌍에 대한 기본값이 설정되고, 객체를 사용하면 로캘 쌍별로 특정 제공자를 매핑할 수 있습니다. |
prompt | string | undefined | 번역 LLM용 커스텀 시스템 프롬프트입니다. {SOURCE_LOCALE} 및 {TARGET_LOCALE} 플레이스홀더를 지원합니다. |
buildMode | "translate" | "cache-only" | "translate" | Compiler가 새 번역을 생성할지, 아니면 캐시된 번역만 사용할지 제어합니다. |
개발 옵션#
dev 키 아래의 옵션은 개발 환경에서의 동작을 제어합니다:
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
dev.usePseudotranslator | boolean | false | LLM을 호출하지 않고 즉시 가짜 번역(예: [!!! Welcome !!!])을 생성합니다. API 키는 필요하지 않습니다. |
dev.translationServerStartPort | number | 60000 | 로컬 번역 서버의 시작 포트입니다. Compiler는 60000-60099 범위에서 사용 가능한 포트를 자동으로 찾습니다. |
dev.translationServerUrl | string | undefined | 번역 서버 URL을 재정의합니다. 커스텀 구성이나 원격 번역 서버를 사용할 때 유용합니다. |
로캘 유지#
localePersistence 아래의 옵션은 사용자가 선택한 로캘을 저장하고 불러오는 방식을 제어합니다:
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
localePersistence.type | string | "cookie" | 유지 메커니즘입니다. 현재는 "cookie"를 지원합니다. |
localePersistence.config.name | string | "locale" | 로캘을 저장할 때 사용하는 쿠키 이름입니다. |
localePersistence.config.maxAge | number | 31536000 | 쿠키의 최대 수명(초)입니다. 기본값은 1년입니다. |
커스텀 유지 로직(localStorage, URL 기반, 헤더)을 구현하려면 Custom Locale Resolvers를 참고하세요.
복수형 처리#
pluralization 아래의 옵션은 자동 복수형 감지 및 생성을 제어합니다:
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
pluralization.enabled | boolean | true | 자동 복수형 감지를 활성화하거나 비활성화합니다. |
pluralization.model | string | "groq:llama-3.1-8b-instant" | 원본 텍스트의 복수형을 감지하는 데 사용하는 LLM 모델입니다. 감지는 번역보다 단순한 작업이므로 더 작고 빠른 모델을 권장합니다. |
복수형 감지가 작동하는 방식은 Automatic Pluralization에서 자세히 확인할 수 있습니다.
환경 변수#
환경 변수는 구성을 재정의하거나 보완하는 데 사용됩니다:
| 변수 | 필요한 경우 | 설명 |
|---|---|---|
LINGO_BUILD_MODE | 선택 사항 | buildMode 구성 옵션을 재정의합니다. "translate" 또는 "cache-only"로 설정하세요. |
LINGODOTDEV_API_KEY | "lingo.dev" 모델을 사용하는 경우 | Lingo.dev 로컬라이제이션 엔진용 API 키입니다. npx lingo.dev@latest login에서 발급받을 수 있습니다. |
OPENAI_API_KEY | "openai:*" 모델을 사용하는 경우 | OpenAI API 키입니다. |
ANTHROPIC_API_KEY | "anthropic:*" 모델을 사용하는 경우 | Anthropic API 키입니다. |
GOOGLE_API_KEY | "google:*" 모델을 사용하는 경우 | Google AI API 키입니다. |
GROQ_API_KEY | "groq:*" 모델을 사용하는 경우 | Groq API 키입니다. |
MISTRAL_API_KEY | "mistral:*" 모델을 사용하는 경우 | Mistral API 키입니다. |
OPENROUTER_API_KEY | "openrouter:*" 모델을 사용하는 경우 | OpenRouter API 키입니다. |
전체 예시#
ts
// 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",
lingoDir: ".lingo",
sourceLocale: "en",
targetLocales: ["es", "de", "fr", "ja"],
useDirective: false,
models: {
"*:*": "lingo.dev",
"*:ja": "anthropic:claude-3-5-sonnet",
},
prompt: "Translate UI text from {SOURCE_LOCALE} to {TARGET_LOCALE}. Keep it concise.",
buildMode: "translate",
dev: {
usePseudotranslator: true,
translationServerStartPort: 60000,
},
localePersistence: {
type: "cookie",
config: {
name: "locale",
maxAge: 31536000,
},
},
pluralization: {
enabled: true,
model: "groq:llama-3.1-8b-instant",
},
});
}