고급 구성

Lingo.dev 컴파일러는 번역 동작을 사용자 정의하고 로컬라이제이션 워크플로우를 최적화하기 위한 광범위한 구성 옵션을 제공합니다.

구성 설정

프로젝트에 컴파일러를 구현할 때 다음 옵션이 포함된 설정 객체를 전달할 수 있습니다:

// 기본 구성
const compilerConfig = {
  sourceRoot: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  debug: false,
  models: {
    // 사용자 정의 모델 구성
    "*:fr": "mistral-saba-24b",
    "en:es": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
  prompt:
    "You are AI translator. You translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.",
};

// Next.js
lingoCompiler.next(compilerConfig)(nextConfig);

// Vite/React Router
lingoCompiler.vite(compilerConfig)(viteConfig);

구성 옵션

  • sourceRoot - lingo/ 디렉토리가 저장될 소스 디렉토리 경로
  • lingoDir - 번역 파일이 포함된 디렉토리 이름(기본값: "lingo")
  • sourceLocale - 애플리케이션의 소스 언어(기본값: "en")
  • targetLocales - 번역할 대상 언어 배열
  • rsc - React 서버 컴포넌트 지원 활성화(기본값: false)
  • debug - 문제 해결을 위한 디버그 로깅 활성화(기본값: false)
  • models - 특정 언어 쌍에 대한 사용자 정의 AI 모델 구성(선택 사항)
  • prompt - 플레이스홀더가 있는 사용자 정의 번역 프롬프트(선택 사항)

권장 Groq 모델

최상의 결과를 위해 특정 로케일에 대해 다음 GROQ 모델의 품질을 테스트하고 검증했습니다:

mistral-saba-24b

  • ar - 아랍어
  • de - 독일어
  • fr - 프랑스어
  • pt-BR - 포르투갈어(브라질)

meta-llama/llama-4-maverick-17b-128e-instruct

  • es - 스페인어
  • ja - 일본어
  • ko - 한국어
  • ru - 러시아어
  • zh - 중국어

파일 처리 제어

번역 건너뛰기

번역하지 않을 요소에 data-lingo-skip 속성을 추가하세요:

<div data-lingo-skip>이 콘텐츠는 번역되지 않습니다</div>

번역 재정의

특정 로케일에 대한 번역을 data-lingo-override- 속성을 사용하여 재정의할 수 있습니다:

<button data-lingo-override-es="¡Hola!" data-lingo-override-fr="Bonjour!">
  Hello
</button>

사용자 정의 모델 구성

컴파일러 구성에서 AI 모델과 프롬프트를 직접 사용자 정의할 수 있습니다:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  models: {
    "*:fr": "mistral-saba-24b",
    "en:es": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "es:fr": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
  prompt:
    "You are a professional translator specializing in technical documentation. Translate from {SOURCE_LOCALE} to {TARGET_LOCALE} while maintaining technical accuracy.",
};

모델 구성

  • 로케일 쌍을 source-locale:target-locale 형식으로 정의
  • 모든 로케일에 대해 *를 와일드카드로 사용
  • 모든 번역에 대한 폴백으로 *:* 사용
  • 사용 가능한 옵션은 GROQ 모델 참조

커스텀 프롬프트

플레이스홀더가 있는 커스텀 번역 프롬프트를 정의할 수 있습니다:

  • {SOURCE_LOCALE} - 소스 언어 코드
  • {TARGET_LOCALE} - 대상 언어 코드

커스텀 용어집을 구축하려면 프롬프트에 용어를 포함하세요. 모범 사례는 기본 컴파일러 프롬프트를 참조하세요.

빌드 정규화

변경 사항을 커밋하기 전에 항상 로컬에서 프로덕션 빌드를 실행하세요:

npm run build

이렇게 하면 lingo/ 디렉토리의 meta.json 및 dictionary.js 파일에 앱에 존재하는 문자열만 포함되고 올바르게 포맷팅되도록 보장합니다.

사전 커밋 훅 설정

husky를 사용하여 자동 정규화를 설정하세요:


# husky 설치

npm install --save-dev husky

# 사전 커밋 훅 추가

npx husky add .husky/pre-commit "npm run build"

환경별 구성

개발

const isDev = process.env.NODE_ENV === "development";

const compilerConfig = {
  debug: isDev,
  targetLocales: isDev ? ["es"] : ["es", "fr", "de", "ja"],
};

CI/CD 통합

자동화된 빌드의 경우, CI 환경이 GROQ API 키에 액세스할 수 있도록 하세요:


# GitHub Actions

GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}

# Vercel

GROQ_API_KEY=gsk_...

# Netlify

GROQ_API_KEY=gsk_...

성능 최적화

증분 빌드

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

  • 파일 지문을 통한 콘텐츠 변경 추적
  • 새로운 또는 수정된 콘텐츠만 번역
  • 변경되지 않은 콘텐츠에 대해 기존 번역 재사용

번들 최적화

  • 로케일별 번들 - 활성 로케일에 대한 번역만 로드
  • 트리 쉐이킹 - 프로덕션 빌드에서 사용되지 않는 번역 제거
  • 코드 분할 - 라우트 기반 앱을 위한 필요시 번역 로드

문제 해결

디버그 모드

문제 해결을 위해 디버그 로깅 활성화:

const compilerConfig = {
  debug: true,
  // ... 기타 옵션
};

일반적인 문제

번역 누락: 로컬에서 npm run build를 실행하고 lingo/ 디렉토리를 커밋했는지 확인하세요. NextJS를 사용하는 경우 모든 파일이 재빌드되도록 .next/ 디렉토리를 삭제해야 할 수 있습니다.

빌드 오류: 환경 변수에 GROQ_API_KEY가 올바르게 설정되어 있는지 확인하세요.

성능 문제: 컴파일 프로세스의 병목 현상을 식별하기 위해 디버그 모드를 활성화하세요.

다음 단계