@lingo.dev/cli
@lingo.dev/cli은 소스 콘텐츠를 로컬라이제이션 엔진으로 보내고, 엔진이 서버에서 번역한 뒤 결과를 다시 디스크에 써 줍니다. --wait를 쓰면 같은 명령에서, lingo pull를 쓰면 나중에 받을 수 있습니다. 기존 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한 뒤 터미널을 닫고, 나중에 결과만 pull하면 됩니다.
결과 기다리기#
lingo push은 소스를 업로드하고 서버 측 워크플로를 시작한 다음, 실행이 제출되자마자 종료됩니다. 번역이 끝날 때까지 기다리지도 않고 결과를 쓰지도 않습니다. 결과는 lingo pull로 가져오거나, --wait(-w)를 넘겨 한 번에 모두 처리할 수 있습니다.
lingo push # submit the run and exit (default)
lingo pull # later: re-attach to the most recent push and download its outputs
lingo push --wait # submit, wait, and write outputs in one command--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에서는 --wait 추가) |
lingo push --backfill-missing | 부트스트랩 — 아직 없는 대상 FILE만 채웁니다 | 첫 push 또는 새 로캘 추가 후 |
lingo push --force | 전체 재번역 — 모든 대상을 덮어씁니다(수동 편집 포함). --yes/-y는 확인 프롬프트를 건너뜁니다 | 드물게(예: 용어집/엔진 변경 후) |
--backfill-missing는 부트스트랩 플래그입니다. 범위가 지정된 새 요청을 수행하고, 누락된 전체 대상 파일만 추가합니다 — 이미 번역된 파일에 새로 추가된 키까지 번역해 넣어 주지는 않습니다(실행에는 "already up-to-date"로 표시되며 해당 키는 건너뜁니다). 계속되는 편집에는 기본 lingo push를 사용하세요.
번역을 수동으로 편집하기#
기본 lingo push는 키 단위로 수동 편집을 보존합니다:
- 대상 문자열을 수정함(소스는 그대로) → 해당 문자열은 유지되고, 다른 키는 계속 업데이트됩니다.
- 수정한 키의 소스가 바뀜 → 그 키에는 새 번역이 생성되어 수동 편집을 대체합니다.
- 새 소스 키가 추가됨 → 수동 편집이 있는 파일에도 번역되어 추가됩니다.