소스 파일을 엔진으로 푸시하고, 실행이 끝날 때까지 기다린 다음, 결과를 디스크에 씁니다.
lingo push [patterns...] [--force] [--backfill-missing] [--yes]기본 동작 — delta push#
인수를 지정하지 않으면 lingo push는 delta-only mode로 실행됩니다:
- config의
files패턴과 일치하는 모든 소스 파일의 해시를 계산합니다 - 각 해시를 lockfile과 비교해 변경된 소스를 찾습니다
- 변경된 소스를 엔진에서 실행할 run으로 업로드합니다
- run이 완료될 때까지 기다립니다
- 결과를 디스크에 씁니다
- 새 소스 해시를 lockfile에 커밋합니다
마지막으로 성공한 push 이후 변경된 소스가 없으면, 명령은 ✓ Nothing to push.를 출력하고 바로 종료됩니다. 서버와 통신하지도 않고, 토큰도 소모하지 않습니다.
인수 및 플래그#
위치 인수: patterns... — scoped push#
lingo push docs/en/about.md
lingo push 'docs/en/**/*.md' 'locales/en.json'push 대상을 특정 파일로 제한합니다(.lingo/config.json에 이미 정의된 패턴과 일치해야 함). 이 경우 명령은 scoped mode로 전환됩니다:
- 이전 소스와 diff를 비교하지 않음 — 변경 여부와 관계없이 일치하는 모든 소스가 범위에 포함된 것으로 처리됩니다.
- 소스 해시가 일치하는 대상이 이미 있으면 서버 측에서 noop 처리 — 엔진은 이를 건너뛰고 CLI는 cached로 보고합니다.
프로젝트 전체를 다시 해시하지 않고 방금 수정한 파일 하나만 정확히 번역하고 싶을 때, 또는 --force로 특정 페이지 하나를 다시 번역하고 싶을 때 유용합니다.
--force / -f#
lingo push docs/en/about.md --force일치하는 모든 대상을 다시 번역하며, 기존 번역은 무시하고 서버 측 캐싱도 우회합니다. 반드시 범위를 지정해야 하며, 위치 패턴 또는 --backfill-missing 중 하나를 사용해야 합니다. 범위 없이 lingo push --force만 단독으로 쓰는 것은 프로젝트 전체를 다시 번역하게 되므로 허용되지 않습니다.
기본적으로 --force는 실행 전에 확인을 요청합니다:
! --force will retranslate every target for pattern(s): docs/en/about.md and
overwrite existing translations. Continue? (Yes, retranslate / Cancel)프롬프트를 건너뛰려면 --yes / -y를 사용하세요(CI에 적합).
--backfill-missing#
lingo push --backfill-missing아직 존재하지 않는 모든 대상을, 설정된 모든 패턴에 걸쳐 번역합니다. config의 모든 패턴에 대해 scoped push를 수행하는 것과 같지만, 없는 파일만 생성합니다. targetLocales에 새 로캘을 추가한 뒤나, 새 프로젝트에서 첫 push를 할 때 사용하세요.
--force와 함께 사용하면 처음부터 전체를 다시 번역할 수 있습니다:
lingo push --backfill-missing --force --yes--yes / -y#
--force 확인 프롬프트를 건너뜁니다. --force 없이 단독으로는 아무 효과가 없습니다.
출력#
성공 시:
Pushing source files to localization engine…
✓ Run run_a8c...: localized 12 target file(s), 4 already up-to-date, uploaded 1 new artifact(s).요약은 다음 항목으로 나뉩니다:
- 대상 파일 N개 로컬라이즈됨 — 엔진이 새 번역을 생성했고 CLI가 이를 파일로 썼습니다.
- N개는 이미 최신 상태 — 서버 측 캐시 적중(소스 일치, 대상 재사용).
- 새 아티팩트 N개 업로드됨 — 엔진이 이전에 본 적 없는 소스(바이너리/대용량 콘텐츠는 한 번 저장한 뒤 이후에는 참조만 함).
- 대상 N개 건너뜀(로컬 편집) — 로컬 대상 해시가 lockfile과 다릅니다. 덮어쓰려면
--force로 다시 실행하세요.
대상별로 실패가 발생하면 CLI는 실패한 각 대상의 오류를 출력하고 0이 아닌 종료 코드로 끝납니다 — CI에서 유용합니다:
✓ Run run_a8c...: localized 10 target file(s).
2 target(s) failed:
locales/de.json: rate limit on engine; retry later
locales/fr.json: timeout재시도 동작#
lockfile은 실행이 완전히 성공했을 때만 업데이트됩니다. 부분 실패(예: 한 로캘에서 타임아웃)가 발생하면 lockfile의 소스 해시는 바뀌지 않으므로, 다음 lingo push는 동일한 diff를 다시 시도합니다 — 수동으로 초기화할 필요가 없습니다.
번역이 시작되기 전에 엔진에서 오류가 발생하면(인증, 검증), 아무것도 기록되지 않고 lockfile도 변경되지 않습니다.
자주 쓰는 패턴#
CI: merge 시 번역#
- run: lingo push --backfill-missing --yes
- run: git add . && git commit -m "chore: refresh translations" && git push--backfill-missing는 안전한 기본값입니다. 아무것도 덮어쓰지 않고, 비어 있는 부분만 채웁니다.
단일 파일 반복 작업#
lingo push docs/en/onboarding.md -f -y카피를 크게 수정한 뒤 소스 파일 하나만 다시 번역합니다. 빠르게 반복 작업하려면 프롬프트를 건너뛰세요.
새 로캘 추가#
.lingo/config.json에서 targetLocales를 늘린 뒤:
lingo push --backfill-missing기존 번역은 다시 번역하지 않고, 전체 코퍼스를 새 로캘로 번역합니다.
