모범 사례

@lingo.dev/compiler의 권장 패턴 및 워크플로우입니다.

개발 워크플로우

기본적으로 Pseudotranslator 사용

권장:

{
  dev: {
    usePseudotranslator: true, // Fast, free, instant feedback
  }
}

이유:

  • 즉각적인 피드백—API 지연 없음
  • 비용 없음—API 크레딧 소비 없음
  • 시각적 마커로 번역 대상 표시
  • 다양한 텍스트 길이로 UI 테스트

실제 번역 품질을 검토할 때만 비활성화하세요.

개발, CI, 프로덕션 환경 분리

개발:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

CI:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

프로덕션:

{
  buildMode: "cache-only",
}

이 워크플로우는:

  • 개발을 빠르고 저렴하게 유지
  • 배포당 한 번 CI에서 실제 번역 생성
  • 프로덕션 빌드를 결정적이고 빠르게 만듦

번역 전략

대부분의 번역은 AI에 맡기기

권장:

<p>Welcome to our application</p>

비권장:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our application
</p>

재정의는 다음의 경우에만 제한적으로 사용하세요:

  • 브랜드명
  • 특정 번역이 필요한 기술 용어
  • 인증이 필요한 법률 텍스트
  • 사람의 검토가 필요한 마케팅 문구

재정의를 일관되게 사용

권장:

// Consistent brand name across app
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

<p>
  Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
    Lingo.dev
  </span>
</p>

하지 말아야 할 것:

<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override—inconsistent

구성

간단하게 시작하기

해야 할 것:

{
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
}

하지 말아야 할 것:

{
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "pt", "it", "ja", "zh", "ar", "ru", "ko"],
  models: {
    "en:es": "groq:...",
    "en:de": "google:...",
    // Complex mappings for 10 locales
  },
  prompt: "Long custom prompt...",
  pluralization: { enabled: false },
}

2-3개의 대상 로케일로 시작하세요. 필요에 따라 추가하세요. 조기 최적화는 피하세요.

Lingo.dev 엔진 사용

해야 할 것:

{
  models: "lingo.dev" // Simple, optimized, supports all features
}

하지 말아야 할 것:

{
  models: {
    "*:*": "groq:...", // Requires manual model selection
  }
}

Lingo.dev 엔진은 다음을 제공합니다:

  • 자동 모델 선택
  • 폴백 처리
  • 번역 메모리
  • 용어집 지원

완전한 제어 또는 비용 최적화가 필요한 경우에만 직접 LLM 제공업체를 사용하세요.

로케일 감지

기본 쿠키 기반 지속성 사용

해야 할 것:

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

사용자 정의가 필요한 경우:

  • localStorage 필요 (SPA 기본 설정)
  • URL 기반 라우팅 (/en/about)
  • 서브도메인 라우팅 (es.example.com)
  • 데이터베이스 기반 사용자 기본 설정

기본값이 맞지 않는 경우에만 사용자 정의 로케일 리졸버를 구현하세요.

버전 관리

.lingo/ 디렉터리 커밋

해야 할 것:

git add .lingo/
git commit -m "chore: update translations"
git push

이유:

  • 버전 관리를 통해 번역 변경 사항을 추적합니다
  • 팀이 번역을 공유합니다
  • CI/CD가 커밋된 번역을 사용합니다
  • 프로덕션 빌드에 API 키가 필요하지 않습니다

CI 실행 후 커밋

해야 할 것 (CI에서):

- name: Generate translations
  run: npm run build

- name: Commit translations
  run: |
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

이를 통해 프로덕션 빌드가 항상 최신 번역을 사용하도록 보장합니다.

CI/CD

CI에서 번역 생성

해야 할 것:

# GitHub Actions
- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: npm run build

하지 말아야 할 것:

# Production build without API key
- name: Build
  run: npm run build # Fails if translations missing

API 키가 있는 CI에서 번역을 생성합니다. 프로덕션 빌드는 캐시된 번역을 사용합니다.

프로덕션에서 cache-only 사용

해야 할 것:

# Production build
LINGO_BUILD_MODE=cache-only npm run build

하지 말아야 할 것:

# Production build with translate mode
LINGO_BUILD_MODE=translate npm run build # Non-deterministic, requires API keys

성능

복수형 선택적 활성화

해야 할 것 (복수형을 사용하는 경우):

{
  pluralization: {
    enabled: true,
  }
}

해야 할 것 (복수형을 사용하지 않는 경우):

{
  pluralization: {
    enabled: false, // Skip plural detection—faster builds
  }
}

복수형 처리는 약간의 오버헤드를 추가합니다(숫자가 포함된 텍스트당 LLM 호출 1회). 필요하지 않은 경우 비활성화하세요.

복수형 처리에 빠른 모델 사용

해야 할 것:

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

하지 말아야 할 것:

{
  pluralization: {
    model: "openai:gpt-4o", // Expensive overkill for plural detection
  }
}

로케일 쌍 매핑 최적화

해야 할 것(비용 최적화):

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // Fast & cheap
    "en:ja": "openai:gpt-4o", // High quality for complex language
    "*:*": "lingo.dev", // Fallback
  }
}

유사한 언어(로망스어, 게르만어)에는 빠르고 저렴한 모델을 사용하세요. 복잡한 언어(CJK, 아랍어)에는 고품질 모델을 사용하세요.

테스트

먼저 의사 번역기로 테스트

해야 할 것:

  1. 의사 번역기 활성화
  2. 모든 UI 컴포넌트 테스트
  3. 레이아웃 문제 수정(오버플로우, 잘림)
  4. 그런 다음 실제 번역 생성

이유:

  • 의사 번역은 즉시 생성됩니다
  • 레이아웃 문제를 조기에 발견합니다
  • API 비용을 절감합니다

모든 대상 로케일 테스트

해야 할 것:

// Test with locale switcher
<LanguageSwitcher /> // Switch between all locales

// Or manually test
setLocale("es"); // Spanish
setLocale("de"); // German
setLocale("fr"); // French

각 로케일을 확인하세요:

  • 번역이 올바르게 표시됨
  • 레이아웃이 텍스트 길이를 수용함
  • 번역되지 않은 텍스트가 없음
  • RTL 언어가 올바르게 렌더링됨(해당하는 경우)

오류 처리

누락된 번역을 우아하게 처리

컴파일러는 번역이 누락된 경우 빌드를 실패시킵니다. 이는 의도적인 것입니다. 손상된 UI를 배포하는 것보다 누락된 번역을 조기에 발견하는 것이 좋습니다.

빌드가 실패하는 경우:

  1. buildMode: "translate"로 실행하여 누락된 번역을 생성합니다
  2. .lingo/metadata.json를 커밋합니다
  3. buildMode: "cache-only"로 프로덕션 빌드를 재시도합니다

번역 실패 모니터링

CI에서 번역 오류를 확인하세요:

- name: Generate translations
  run: npm run build 2>&1 | tee build.log

- name: Check for translation errors
  run: |
    if grep -q "Failed to generate translation" build.log; then
      echo "Translation generation failed"
      exit 1
    fi

유지보수

정기적인 정리

사용하지 않는 번역을 주기적으로 제거하세요:

# Backup first
cp .lingo/metadata.json .lingo/metadata.backup.json

# Manual: Search for each hash in codebase, remove if not found

# Automated (coming soon):
npx @lingo.dev/compiler clean

파일 크기 모니터링

.lingo/metadata.json는 앱과 함께 증가합니다. 파일이 커지면(>5 MB):

  • 여러 앱으로 분할하는 것을 고려하세요
  • 오래된 번역을 아카이브하세요
  • 자동화된 정리를 사용하세요

일반적인 안티 패턴

오버라이드를 과도하게 사용하지 마세요

나쁜 예:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our app
</p>

AI가 일반 텍스트를 처리하도록 하세요. 오버라이드는 예외적인 경우에만 사용합니다.

API 키를 커밋하지 마세요

나쁜 예:

// next.config.ts
{
  models: "lingo.dev",
  apiKey: "your-api-key-here", // NEVER commit API keys
}

좋은 예:

# .env (not committed)
LINGODOTDEV_API_KEY=your_key_here

프로덕션에서 translate 모드를 사용하지 마세요

나쁜 예:

// production config
{
  buildMode: "translate", // Non-deterministic, requires API keys
}

좋은 예:

{
  buildMode: "cache-only", // Deterministic, no API keys
}

버전 관리를 건너뛰지 마세요

나쁜 예:

# .gitignore
.lingo/ # DON'T ignore translations

좋은 예:

# .gitignore
.env # Ignore API keys only

마이그레이션 전략

점진적 롤아웃

기존 앱에 컴파일러를 추가할 때:

  1. 1-2개 로케일로 시작
  2. 의사 번역기 활성화
  3. 모든 페이지 테스트
  4. 레이아웃 문제 수정
  5. 더 많은 로케일 추가
  6. 실제 번역 생성
  7. 배포

첫날부터 20개 로케일을 번역하려고 하지 마세요.

점진적 도입

전체 앱을 한 번에 번역할 필요는 없습니다:

{
  useDirective: true, // Opt-in per file
}

번역하려는 파일에 'use i18n' 지시문을 추가하세요:

'use i18n'; // This file gets translated

export function HomePage() {
  return <h1>Welcome</h1>;
}

다른 파일은 옵트인할 때까지 번역되지 않은 상태로 유지됩니다.

다음 단계