구성 참조 - Lingo.dev Compiler

모든 @lingo.dev/compiler 구성 옵션에 대한 완전한 참조입니다.

핵심 옵션

옵션	타입	기본값	설명
`sourceRoot`	`string`	`"src"`	번역할 소스 코드가 포함된 루트 디렉토리
`lingoDir`	`string`	`".lingo"`	번역 메타데이터 및 캐시를 위한 디렉토리
`sourceLocale`	`string`	(필수)	소스 로케일 코드 (예: `"en"`, `"en-US"`)
`targetLocales`	`string[]`	(필수)	번역할 대상 로케일 코드 배열
`useDirective`	`boolean`	`false`	옵트인 번역을 위해 `'use i18n'` 지시문을 요구할지 여부
`models`	`string \| object`	`"lingo.dev"`	번역 제공자 구성 (번역 제공자 참조)
`prompt`	`string`	`undefined`	사용자 정의 번역 프롬프트 템플릿
`buildMode`	`"translate" \| "cache-only"`	`"translate"`	빌드 모드 (빌드 모드 참조)

예제

{
  sourceRoot: "./app",
  lingoDir: ".lingo",
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "ja"],
  useDirective: false,
  models: "lingo.dev",
  buildMode: "translate",
}

개발 옵션

dev 객체를 통해 개발 관련 동작을 구성합니다:

옵션	타입	기본값	설명
`dev.usePseudotranslator`	`boolean`	`false`	실제 AI 대신 가짜 번역 사용 (개발 시 권장)
`dev.translationServerStartPort`	`number`	`60000`	번역 서버의 시작 포트 (60000-60099 범위에서 자동 검색)
`dev.translationServerUrl`	`string`	`undefined`	사용자 정의 번역 서버 URL (고급 사용)

예제

{
  dev: {
    usePseudotranslator: true, // Fast fake translations
    translationServerStartPort: 60000, // Default port range
  }
}

왜 pseudotranslator를 사용하나요? API 호출 없이 즉시 사용 가능하고, 번역되는 내용을 정확히 보여주며, 다양한 텍스트 길이로 UI를 테스트할 수 있습니다. 모두 API 비용 없이 가능합니다.

로케일 지속성

로케일 변경이 지속되는 방식을 구성합니다:

옵션	타입	기본값	설명
`localePersistence.type`	`"cookie"`	`"cookie"`	현재 쿠키 기반 지속성만 지원됩니다
`localePersistence.config.name`	`string`	`"locale"`	쿠키 이름
`localePersistence.config.maxAge`	`number`	`31536000`	쿠키 최대 유효 기간(초 단위, 기본값: 1년)

예제

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "user-locale",
      maxAge: 31536000, // 1 year
    },
  },
}

커스텀 지속성이 필요하신가요? 커스텀 로케일 리졸버를 구현하여 localStorage, URL 파라미터 또는 데이터베이스 지속성을 사용할 수 있습니다.

복수형 처리

자동 복수형 감지를 구성합니다:

옵션	타입	기본값	설명
`pluralization.enabled`	`boolean`	`true`	자동 ICU MessageFormat 감지 활성화
`pluralization.model`	`string`	`"groq:llama-3.1-8b-instant"`	복수형 감지에 사용할 LLM 모델

예제

{
  pluralization: {
    enabled: true,
    model: "groq:llama-3.1-8b-instant", // Fast model for plural detection
  },
}

작동 방식: 컴파일러가 텍스트에서 복수형을 감지하고(예: "You have 5 items") ICU MessageFormat({count, plural, one {1 item} other {# items}})으로 변환합니다.

성능을 위한 비활성화: 복수형을 사용하지 않는 경우, 이 기능을 비활성화하여 복수형 처리를 위한 LLM 호출을 건너뛸 수 있습니다.

번역 프로바이더

models 옵션은 번역에 사용할 LLM 프로바이더를 구성합니다.

간단한 구성

모든 번역에 단일 프로바이더를 사용합니다:

{
  models: "lingo.dev" // Recommended: Lingo.dev Engine
}

고급 구성

세밀한 제어를 위해 로케일 쌍 매핑을 사용하세요:

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // English to Spanish
    "en:de": "google:gemini-2.0-flash",      // English to German
    "*:fr": "openai:gpt-4o",                 // Any locale to French
    "*:*": "anthropic:claude-3-5-sonnet",    // Fallback for all others
  }
}

패턴:

"source:target": 특정 로케일 쌍 (예: "en:es")
"*:target": 모든 소스에서 특정 타겟으로 (예: "*:de")
"source:*": 특정 소스에서 모든 타겟으로 (예: "en:*")
"*:*": 모든 쌍에 대한 폴백

프로바이더 구문 및 API 키 설정은 번역 프로바이더를 참조하세요.

커스텀 번역 프롬프트

플레이스홀더를 사용하여 번역 프롬프트를 커스터마이징하세요:

{
  prompt: `Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.
Use a formal tone and preserve all technical terms.
Do not translate brand names or product names.`
}

사용 가능한 플레이스홀더:

{SOURCE_LOCALE}: 소스 로케일 코드 (예: "en")
{TARGET_LOCALE}: 타겟 로케일 코드 (예: "es")

컴파일러는 번역되는 텍스트에 대한 컨텍스트(컴포넌트 위치, 주변 요소)를 커스텀 프롬프트에 추가합니다.

환경 변수 오버라이드

환경 변수를 통해 구성을 오버라이드하세요:

# Override build mode
LINGO_BUILD_MODE=cache-only npm run build

# Set API key
LINGODOTDEV_API_KEY=your_key_here
GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=...

전체 예제

// 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, {
    // Core
    sourceRoot: "./app",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,

    // Build mode
    buildMode: process.env.NODE_ENV === "production" ? "cache-only" : "translate",

    // Models
    models: {
      "en:es": "groq:llama-3.3-70b-versatile",
      "*:*": "lingo.dev",
    },

    // Custom prompt
    prompt: "Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}. Use a professional tone.",

    // Development
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },

    // Locale persistence
    localePersistence: {
      type: "cookie",
      config: {
        name: "locale",
        maxAge: 31536000,
      },
    },

    // Pluralization
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

TypeScript 타입

타입 안전성을 위해 구성 타입을 임포트하세요:

import type { LingoConfig } from "@lingo.dev/compiler";

const config: LingoConfig = {
  // ...config
};

자주 묻는 질문

모든 옵션을 구성해야 하나요? 아니요. sourceLocale와 targetLocales만 필수입니다. 나머지는 모두 합리적인 기본값을 가지고 있습니다.

sourceRoot와 lingoDir의 차이점은 무엇인가요? sourceRoot는 소스 코드가 위치한 곳입니다 (예: ./app, src). lingoDir는 번역 메타데이터가 저장되는 곳입니다 (기본값: .lingo).

로케일별로 다른 모델을 사용할 수 있나요? 네. models 옵션에서 로케일 쌍 매핑을 사용하세요. 번역 프로바이더를 참조하세요.

.lingo/를 git에 커밋해야 하나요? 네. .lingo/ 디렉토리에는 번역 메타데이터와 캐시가 포함되어 있습니다. 코드와 함께 버전 관리되어야 합니다.

복수형을 비활성화하려면 어떻게 해야 하나요? pluralization.enabled: false로 설정하세요. 이렇게 하면 복수형 감지를 건너뛰고 LLM 호출을 줄일 수 있습니다.

다음 단계

번역 제공자 — LLM 제공자 구성
빌드 모드 — translate와 cache-only 이해하기
사용자 정의 로케일 리졸버 — 사용자 정의 로케일 감지 구현
모범 사례 — 권장 구성