@lingo.dev/cli는 소스 콘텐츠를 로컬라이제이션 엔진으로 보내고, 엔진이 번역을 생성하는 동안 기다린 뒤, 결과를 다시 디스크에 씁니다. 기존 npx lingo.dev 방식의 대체재로, 같은 프로젝트를 다루지만 아키텍처는 근본적으로 다릅니다.
기존 CLI와 달라진 점#
기존 CLI(npx lingo.dev run)는 문자열을 추출하고, 사용 중인 머신에서 직접 LLM을 호출한 뒤, 같은 머신에서 한 번에 파일까지 써 주는 방식이었습니다. 현재 CLI는 이 작업을 push와 pull로 나눕니다:
- **
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 | 부트스트랩 — 아직 없는 대상 FILE만 채웁니다 | 첫 push 또는 새 로캘 추가 후 |
lingo push --force | 전체 재번역 — 모든 대상을 덮어씁니다(수동 편집 포함). --yes/-y는 확인 프롬프트를 건너뜁니다 | 드물게(예: 용어집/엔진 변경 후) |
--backfill-missing는 부트스트랩 플래그입니다. 범위가 지정된 새 요청을 수행하고, 누락된 전체 대상 파일만 추가합니다 — 이미 번역된 파일에 새로 추가된 키까지 번역해 넣어 주지는 않습니다(실행에는 "already up-to-date"로 표시되며 해당 키는 건너뜁니다). 계속되는 편집에는 기본 lingo push를 사용하세요.
번역을 수동으로 편집하기#
기본 lingo push는 키 단위로 수동 편집을 보존합니다:
- 대상 문자열을 수정함(소스는 그대로) → 해당 문자열은 유지되고, 다른 키는 계속 업데이트됩니다.
- 수정한 키의 소스가 바뀜 → 그 키에는 새 번역이 생성되어 수동 편집을 대체합니다.
- 새 소스 키가 추가됨 → 수동 편집이 있는 파일에도 번역되어 추가됩니다.
