@lingo.dev/cli는 소스 콘텐츠를 로컬라이제이션 엔진에 전송하고, 엔진이 번역을 생성하는 동안 기다린 뒤, 결과를 다시 디스크에 기록합니다. 기존 npx lingo.dev 방식를 대체하는 CLI로, 같은 프로젝트이지만 아키텍처는 근본적으로 다릅니다.
기존 CLI와 무엇이 달라졌나#
기존 CLI(npx lingo.dev run)는 문자열을 추출하고, 사용 중인 머신에서 직접 LLM을 호출한 뒤, 동기식 단일 패스로 파일을 작성했습니다. 새 CLI는 비동기 방식이 기본인 구조입니다:
- **
lingo push**는 소스를 엔진에 업로드하고, 서버 측 워크플로를 시작한 뒤, 완료될 때까지 기다리거나 실행 ID를 반환하고 즉시 종료합니다 - **
lingo pull**는 가장 최근 push의 결과를 가져옵니다. 번역 도중 터미널을 닫았거나, 다른 머신에서 pull하는 경우에도 동작합니다 - lockfile(
.lingo/lock.json)은 각 대상의 마지막 서버 버전을 추적하므로, 덮어쓰기 전에 충돌 감지로 로컬 수정 사항을 표시할 수 있습니다
덕분에 기존 CLI로는 할 수 없던 두 가지가 가능해졌습니다. 터미널을 붙잡아 두지 않는 장시간 번역, 그리고 push를 실행한 머신이 아닌 다른 머신(또는 CI)에서 결과를 pull하는 것입니다.
결과 기다리기#
현재 lingo push는 소스를 업로드하고, 서버 측 워크플로를 시작한 뒤, 완료될 때까지 기다렸다가 결과를 기록합니다. 이 모든 과정이 하나의 명령으로 이뤄집니다. --wait(-w)를 넘기면 이런 블로킹 동작이 명시적으로 적용됩니다. 나중에 lingo pull로 완료된 실행에 다시 연결할 수도 있습니다.
lingo push # submit, wait, and write outputs (current default)
lingo push --wait # same thing, made explicit
lingo pull # later: re-attach to the most recent push and download its outputs곧 바뀝니다: 예정된 릴리스부터 기본값이 비동기로 전환됩니다. lingo push는 실행을 제출한 뒤 즉시 종료되고, 완료된 번역은 lingo pull로 내려받게 됩니다. 그리고 --wait(-w)는 다시 한 번 단일 명령의 블로킹 플로를 선택하는 방식이 됩니다.
--wait(-w)는 워크플로가 끝날 때까지 대기한 뒤, 같은 명령에서 결과를 기록합니다.lingo pull는 이 프로젝트의 가장 최근 push에 다시 연결해 결과를 다운로드합니다. 터미널을 닫은 뒤에도 동작합니다. 실행 상태는 머신별로~/.lingo/runs/<project-hash>.json에 저장되므로,pull는 같은 머신에서 이어집니다.
인증: 두 명령 모두 LINGO_API_KEY(또는 --api-key, 또는 lingo login 세션)을 읽습니다. CI에서는 LINGO_API_KEY만 설정하면 추가 설정은 필요 없습니다.
push 모드#
| 명령어 | 모드 | 사용 시점 |
|---|---|---|
lingo push | 증분 — 소스를 .lingo/lock.json와 비교해 변경분만 확인하고, 기존 대상에는 새 키와 변경된 키만 번역하며, 나머지는 그대로 유지합니다 | 일반적인 실행 / CI |
lingo push --backfill-missing | 부트스트랩 — 아직 존재하지 않는 대상 파일을 채웁니다 | 첫 push 또는 새 로캘 추가 후 |
lingo push --force | 전체 재번역 — 모든 대상(수동 수정 포함)을 덮어씁니다. --yes/-y를 사용하면 확인 프롬프트를 건너뜁니다 | 드물게 사용(예: 용어집/엔진 변경 후) |
--backfill-missing는 부트스트랩 플래그입니다. 범위가 지정된 새 요청을 수행하고, 누락된 전체 대상 파일만 추가합니다. 즉, 이미 번역된 파일에 새로 추가된 키까지 번역해 넣지는 않습니다(실행에는 "already up-to-date"로 표시되며 해당 키는 건너뜁니다). 지속적인 수정 작업에는 일반 lingo push를 사용하세요.
번역을 수동으로 편집하기#
일반 lingo push는 키 단위로 수동 수정을 보존합니다:
- 대상 문자열을 수정했지만 해당 소스는 바뀌지 않음 → 그 문자열은 유지되고, 다른 키는 계속 업데이트됩니다.
- 수정한 키의 소스가 변경됨 → 해당 키에 새 번역이 생성되며, 기존 수동 수정은 대체됩니다.
- 새 소스 키가 추가됨 → 번역되어 추가되며, 수동 수정이 있는 파일에도 반영됩니다.
