알파
Lingo.dev Compiler는 현재 알파 단계입니다. 아직 안정적이지 않으며 프로덕션 사용은 권장되지 않고, API는 릴리스마다 변경될 수 있습니다.
Lingo.dev Compiler는 빌드 중 새 번역을 생성할지 여부를 제어하는 두 가지 빌드 모드로 동작합니다. 안정적인 개발, CI, 프로덕션 파이프라인을 구축하려면 이 모드를 정확히 이해하는 것이 중요합니다.
두 가지 모드#
| 모드 | 동작 | 사용 시점 |
|---|---|---|
"translate" | 설정된 LLM 제공자를 호출해 누락된 번역을 생성합니다. 캐시된 번역은 재사용됩니다. | 새로 추가되거나 변경된 텍스트를 번역해야 하는 개발 및 CI 환경 |
"cache-only" | .lingo/metadata.json의 번역만 사용합니다. 번역이 하나라도 누락되면 빌드가 실패합니다. | 외부 API 호출 없이 일관된 결과를 보장해야 하는 프로덕션 빌드 |
translate 모드 작동 방식#
translate 모드에서는 Compiler가 각 번역 가능한 문자열을 .lingo/metadata.json와 비교합니다. 캐시된 번역이 있고 원문이 변경되지 않았다면 캐시된 버전을 사용합니다. 문자열이 새로 추가되었거나 수정된 경우에는 Compiler가 설정된 번역 제공자를 호출해 번역을 생성하고 캐시를 업데이트합니다.
{
buildMode: "translate",
}이 모드는 기본값입니다. 즉시 가짜 번역을 제공하는 pseudotranslator와 실제 LLM 제공자 모두와 함께 사용할 수 있습니다.
cache-only 모드 작동 방식#
cache-only 모드에서는 Compiler가 .lingo/metadata.json의 번역만 사용합니다. LLM 호출은 전혀 발생하지 않습니다. 번역 가능한 문자열 중 하나라도 캐시에 없으면, 누락된 문자열 목록이 포함된 오류와 함께 빌드가 실패합니다.
.lingo/metadata.json는 반드시 버전 관리에 커밋되어 있어야 합니다. cache-only 모드의 프로덕션 빌드는 이 파일이 로컬에만 생성되어 있는 것이 아니라 저장소에 포함되어 있어야 정상적으로 동작합니다.
{
buildMode: "cache-only",
}이 모드는 항상 동일한 결과를 내는 빌드를 보장합니다. 즉, 같은 소스 코드와 같은 캐시라면 언제나 동일한 출력이 생성됩니다. 또한 프로덕션 빌드에서 외부 API 의존성도 제거할 수 있습니다.
권장 워크플로#
개발 - pseudotranslator
API 호출 없이 즉각적인 피드백을 받으려면 pseudotranslator를 활성화하세요:
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}의사 번역은 [!!! Welcome !!!]처럼 표시되므로, 번역되지 않은 문자열을 쉽게 찾고 길이가 다양한 텍스트로 레이아웃을 테스트할 수 있습니다.
CI - translate 모드
buildMode: "translate"와 실제 LLM 제공자를 함께 사용해 실행하세요. CI 작업은 새로 추가되거나 변경된 문자열의 번역을 생성하고, 업데이트된 .lingo/metadata.json를 다시 저장소에 커밋합니다.
# CI environment
LINGO_BUILD_MODE=translate npm run build프로덕션 - cache-only 모드
미리 생성된 번역만 사용하려면 buildMode: "cache-only"로 배포하세요. 프로덕션 환경에서는 API 키가 필요하지 않습니다.
# Production environment
LINGO_BUILD_MODE=cache-only npm run build환경 변수로 재정의#
LINGO_BUILD_MODE 환경 변수는 buildMode 설정 옵션보다 우선합니다. 덕분에 환경이 달라도 동일한 설정 파일을 그대로 사용할 수 있습니다:
# Override in any environment
LINGO_BUILD_MODE=cache-only npm run build환경 변수는 설정 파일의 값보다 우선 적용됩니다.
CI 예시#
# .github/workflows/translate.yml
name: Generate Translations
on:
push:
branches: [main]
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
env:
LINGO_BUILD_MODE: translate
LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
- uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "chore: update translations"
file_pattern: ".lingo/metadata.json"항상 .lingo/metadata.json를 버전 관리에 커밋하세요. cache-only 모드의 프로덕션 빌드는 이 파일에 의존합니다. 파일이 없거나 내용이 불완전하면 빌드가 실패합니다.
