빌드 모드

@lingo.dev/compiler는 번역이 생성되는 시기와 방법을 제어하는 두 가지 빌드 모드를 지원합니다.

모드 개요

모드사용 시기API 호출동작
translate개발, CI예구성된 LLM을 사용하여 누락된 번역 생성
cache-only프로덕션 빌드아니오.lingo/metadata.json의 캐시된 번역만 사용

Translate 모드

목적: 빌드 중 필요에 따라 번역을 생성합니다.

{
  buildMode: "translate"
}

동작:

  • 번역 가능한 텍스트를 찾기 위해 코드 스캔
  • 기존 번역에 대해 .lingo/metadata.json 확인
  • 구성된 LLM 제공자를 통해 누락된 번역 생성
  • 새 번역으로 .lingo/metadata.json 업데이트
  • 번역 생성 실패 시 빌드 실패

사용 시기:

  • 로컬 개발 (usePseudotranslator: true 사용)
  • CI/CD 파이프라인 (실제 LLM 제공자 사용)
  • 초기 설정 및 번역 생성

필요 사항:

  • 구성된 제공자에 대한 유효한 API 키 (또는 pseudotranslator 활성화)
  • LLM 제공자에 대한 네트워크 연결

Cache-Only 모드

목적: 사전 생성된 번역만 사용하여 빌드합니다.

{
  buildMode: "cache-only"
}

동작:

  • .lingo/metadata.json에서 번역 읽기
  • API 호출 없음
  • 로케일에 대한 번역이 누락된 경우 빌드 실패
  • 빠르고 결정론적인 빌드

사용 시기:

  • 프로덕션 빌드
  • API 키 없는 배포
  • 네트워크 액세스가 제한된 환경

필요 사항:

  • 모든 로케일에 대한 번역이 포함된 .lingo/metadata.json
  • CI 또는 개발 환경에서 사전 생성된 번역

권장 워크플로우

1. 로컬 개발

즉각적인 피드백을 위해 pseudotranslator를 사용하세요:

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

장점:

  • 즉각적인 가짜 번역
  • API 비용 없음
  • 번역되는 내용을 정확히 확인
  • 다양한 텍스트 길이로 UI 테스트

2. CI/CD 파이프라인

CI에서 실제 번역 생성:

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

CI 설정:

# GitHub Actions example
- name: Install dependencies
  run: pnpm install

- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: pnpm run build

- name: Commit translations
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

장점:

  • 배포당 한 번만 실제 번역 생성
  • 버전 관리에 커밋됨
  • 프로덕션 빌드에 API 키 불필요

3. 프로덕션 빌드

캐시된 번역만 사용:

{
  buildMode: "cache-only",
}

장점:

  • API 키 불필요
  • 빠른 빌드
  • 결정론적—동일한 입력은 항상 동일한 출력 생성
  • 외부 네트워크 의존성 없음

환경 변수 재정의

환경 변수를 통한 빌드 모드 재정의:

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

# Force translate mode
LINGO_BUILD_MODE=translate npm run build

이는 설정을 수정하지 않고 cache-only를 강제하려는 배포 환경에서 유용합니다.

누락된 번역 처리

translate 모드에서

번역이 실패하는 경우:

Error: Failed to generate translation for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - Provider: lingo.dev
  - Reason: API key invalid

해결 방법: API 키를 수정하고 빌드를 다시 실행합니다.

cache-only 모드에서

번역이 누락된 경우:

Error: Missing translations for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - File: app/page.tsx:12

Run with buildMode: "translate" to generate missing translations.

해결 방법: translate 모드로 빌드를 실행하여 누락된 번역을 생성한 다음 .lingo/를 커밋합니다.

증분 번역

컴파일러는 콘텐츠 해싱을 사용하여 번역이 필요한 항목을 결정합니다:

  1. 번역 가능한 각 문자열은 안정적인 해시를 받습니다
  2. 해시는 원본 텍스트 + 컨텍스트를 기반으로 합니다
  3. 해시가 .lingo/metadata.json에 존재하면 번역이 재사용됩니다
  4. 새로운 텍스트나 변경된 텍스트만 재번역을 트리거합니다

결과: 번역 비용은 한 번만 지불하면 됩니다. 이후 빌드는 캐시된 번역을 재사용합니다.

CI 구성 예제

GitHub Actions

name: Generate Translations

on:
  push:
    branches: [main]
  pull_request:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Generate translations
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
        run: pnpm run build

      - name: Commit translations
        if: github.event_name == 'push'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .lingo/
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
          git push

GitLab CI

stages:
  - translate

generate-translations:
  stage: translate
  script:
    - pnpm install
    - pnpm run build
    - git config user.name "GitLab CI"
    - git config user.email "[email protected]"
    - git add .lingo/
    - git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
    - git push origin HEAD:$CI_COMMIT_REF_NAME
  only:
    - main

자주 묻는 질문

프로덕션에서 API 키가 필요한가요? 아니요. 프로덕션에서는 buildMode: "cache-only"를 사용하세요. 번역은 CI에서 미리 생성됩니다.

CI에서 번역 생성을 잊어버리면 어떻게 되나요? 프로덕션 빌드가 누락된 번역 목록과 함께 명확한 오류로 실패합니다. CI에서 번역을 생성하고 커밋한 후 재배포하세요.

프로덕션에서 translate 모드를 사용할 수 있나요? 가능하지만 권장하지 않습니다. 빌드가 비결정적이 되고 프로덕션에서 API 키가 필요합니다. CI에서 번역을 생성하는 것이 더 좋습니다.

로컬에서 cache-only 모드를 테스트하려면 어떻게 하나요?

  1. translate 모드로 번역을 생성합니다
  2. cache-only 모드로 전환합니다
  3. 빌드를 실행하면 캐시된 번역을 사용하여 성공해야 합니다

원본 텍스트가 변경되면 어떻게 되나요? 해시가 변경되므로 새로운 번역이 생성됩니다(translate 모드에서). 이전 번역은 기록을 위해 .lingo/metadata.json에 보관됩니다.

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

다음 단계