CLI 버전 0으로 파일 번역하기

버전이 고정된 패키지로 소규모 레거시 카탈로그 실행을 재현하고 결과물과 Lockfile을 확인합니다.

i18n.json이 설치된 프로젝트나 격리된 레거시 테스트 환경에서 이 절차를 사용하세요. 이 절차는 lingo.dev@0.138.10을 대상으로 하며, 해당 매니페스트는 Node.js 18 이상을 요구합니다. 먼저 node --version과 설치된 lingo --version을 확인하세요. 새 프로젝트에서는 최신 빠른 시작 가이드를 따르세요.

기록된 패키지 사용하기 #

기존 프로젝트에서는 의존성 버전을 고정된 상태로 유지하세요. 별도의 테스트 환경에서는 사용 중인 패키지 관리자를 선택하세요.

sh
npm install --save-dev lingo.dev@0.138.10
pnpm add --save-dev lingo.dev@0.138.10
yarn add --dev lingo.dev@0.138.10
bun add --dev lingo.dev@0.138.10

설치 명령은 하나만 실행하세요. npm exec -- lingo, pnpm exec lingo, yarn lingo 또는 bun run lingo를 통해 로컬 바이너리를 실행하세요. 아래 예제에서는 이를 lingo로 줄여 표기합니다. 윈도에서도 버전이 고정된 로컬 설치본을 사용하고 패키지 관리자 바이너리를 실행하면, 패키지 이름으로 실행할 명령을 찾는 방식에 의존하지 않을 수 있습니다.

카탈로그와 설정 만들기 #

프로젝트를 둘 디렉터리에서 lingo init을 실행하세요. 이 명령은 i18n.json을 생성합니다. 파일이 이미 있다면 다시 초기화하지 말고 기존 파일을 유지하세요. locales/en.json을 만드세요.

json
{
  "welcome": "Welcome back",
  "button.save": "Save changes"
}

이에 맞는 JSON 버킷을 사용하세요.

json
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": { "source": "en", "targets": ["es"] },
  "buckets": {
    "json": { "include": ["locales/[locale].json"] }
  }
}

version은 패키지 버전이 아니라 설정 스키마 버전입니다. 이 패턴은 locales/en.json에서 영어를 읽어 locales/es.json에 스페인어를 기록합니다.

번역 백엔드 설정하기 #

Lingo.dev를 사용하는 경우 셸의 비밀 정보 관리 기능을 통해 LINGO_API_KEY을 제공하세요. 사용할 engineId를 설정에 추가하고, 해당 키로 그 로컬라이제이션 엔진을 통해 번역할 수 있는지 확인하세요. 생략하면 백엔드가 암묵적으로 선택한 항목이 적용됩니다. 현재 서비스 정책에 따라 식별자를 명시해야 할 수도 있습니다.

공급자에 직접 연결하는 버전 0 설정은 별도로 선택할 수 있는 방식이며, 공급자별 인증 정보나 접속 가능한 Ollama 서비스가 필요합니다. 각 필드는 설정 레퍼런스에서 확인할 수 있습니다. 이 필드들은 현재 CLI의 JSON 설정에 넣으면 안 됩니다.

실행하고 결과 확인하기 #

sh
lingo run

locales/es.json에서 키와 실제 번역 값을 모두 살펴보세요. 저장 메시지가 여전히 의도한 동작을 나타내는지 확인하세요. 애플리케이션에 연결할 때는 실제로 사용하는 카탈로그 로더로 대상 카탈로그를 불러오세요. 승인된 결과물과 설정, i18n.lock을 함께 커밋하세요.

원문이 바뀌지 않은 상태에서 일반적으로 실행하면 기존 대상 값이 유지되어야 합니다. 원문이 바뀌거나 강제로 실행하면 이 값들이 대체될 수 있습니다. 대상 로캘이나 특정 키로 범위를 제한해 실행하면 기존 원문 기준선은 갱신되지 않으며, 동결 모드에서도 Lockfile이 없으면 새로 초기화될 수 있습니다. 제한된 범위의 결과만으로 프로젝트 전체가 갱신되었다고 판단하기 전에 기준선 확정을 읽어보세요.

개발 중에는 lingo run --watch이 Ctrl+C로 중지할 때까지 원문 변경을 감지합니다. 테스트 환경을 확장하기 전에 기존 번역 채택과 대상 번역의 수동 관리 권한을 살펴보세요.