Docs
Create an account

lingo push

Max PrilutskiyCEO 겸 공동창업자Updated 19일 전 · 6 min read

소스 파일을 엔진으로 푸시하고, 실행이 끝날 때까지 기다린 다음, 결과를 디스크에 씁니다.

text
lingo push [patterns...] [--key <pattern>] [--force] [--backfill-missing] [--yes] [--wait] [--estimate]

기본 동작 — delta push#

인수를 지정하지 않으면 lingo push는 delta-only mode로 실행됩니다:

  1. config의 files 패턴과 일치하는 모든 소스 파일의 해시를 계산합니다
  2. 각 해시를 lockfile과 비교해 변경된 소스를 찾습니다
  3. 변경된 소스를 엔진에서 실행할 run으로 업로드합니다
  4. run이 완료될 때까지 기다립니다
  5. 결과를 디스크에 씁니다
  6. 새 소스 해시를 lockfile에 커밋합니다

마지막으로 성공한 push 이후 변경된 소스가 없으면, 명령은 ✓ Nothing to push.를 출력하고 바로 종료됩니다. 서버와 통신하지도 않고, 토큰도 소모하지 않습니다.

인수 및 플래그#

위치 인수: patterns... — scoped push#

bash
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로 특정 페이지 하나를 다시 번역하고 싶을 때 유용합니다.

--key <pattern>#

bash
lingo push --key auth.login
lingo push --key auth.login --key billing.plan
lingo push --key "auth.*"

패턴이 지정한 키만 다시 번역해 기존 번역에 병합하고, 나머지 모든 키는 바이트 단위까지 그대로 유지합니다. 반복해서 사용할 수 있으며, 패턴마다 --key를 하나씩 쓰면 됩니다.

키 범위는 소스 diff를 무시하므로, 소스 텍스트가 전혀 바뀌지 않은 키도 다시 번역됩니다. 이게 바로 이 플래그의 핵심입니다. 파일 전체 비용을 들이지 않고도 문구 변경, 모델 전환, 용어집 업데이트 후 몇 개의 문자열만 다시 처리할 수 있는 공식 지원 방식입니다.

--force만 추가되며, 파일 전체에 대한 확인 프롬프트는 표시되지 않습니다.

각 키의 처리 방식#

--key에 지정됨번역에 있음결과
예예다시 번역됨
예아니요번역 후 추가됨
아니요예기존 번역 유지
아니요아니요아예 기록되지 않음

마지막 행이 키 범위를 일반 push와 구분하는 지점입니다. 마지막 전체 push 이후 소스에 추가된 키는 소스 텍스트 형태로 번역에 그대로 들어가지 않습니다. 제외된 채로 남아 있고, 다음 일반 lingo push에서 번역됩니다.

패턴이 일치하는 방식#

패턴적용 대상
auth.loginauth.login 및 auth.login.title — auth.login_url에는 절대 일치하지 않음
authauth와 그 전체 하위 트리 — authority에는 절대 일치하지 않음
"auth.*"auth 아래의 모든 항목(auth.login_url 포함). 단, auth는 제외
"auth*"위 내용에 더해 authority까지 포함 — 경계가 전혀 없음

패턴은 키와 정확히 일치하거나, .·/·-·[ 경계에서 끝나는 접두사로 일치하거나, glob로 일치합니다. 배열 멤버는 대괄호 경계를 통해 접근할 수 있으므로 nav.items는 nav.items[0].title를 포함합니다.

glob는 따옴표로 감싸세요. 셸이 먼저 이를 확장합니다. zsh에서는 따옴표 없는 --key auth.*가 no matches found와 함께 중단되거나, 디렉터리에 auth.json 같은 파일이 있으면 조용히 그 파일명으로 바뀝니다. 쉼표로 구분한 값은 목록이 아닙니다. --key "a,b"는 아무것도 일치하지 않는 하나의 리터럴 패턴일 뿐입니다. 대신 플래그를 반복해서 사용하세요.

거부되는 경우#

키 범위는 요청한 것보다 더 많이 수행하지 않습니다. 그 대신 해당 내용을 알리고 건너뜁니다:

  • 아직 번역이 없는 로캘. 병합할 대상이 없으므로 해당 로캘을 표시하고 건너뜁니다. 먼저 --backfill-missing로 한 번 번역한 뒤 --key를 사용하세요.
  • 키를 생략할 수 없는 형식 — 문서가 편집되는 순간 키가 바뀌는 문서 형식과, 파일이 유효한 상태를 유지하려면 복수형 범주가 필요한 xcode-stringsdict입니다. 전체 목록은 형식에서 확인할 수 있습니다. 이러한 파일은 경고와 함께 제외되므로, 푸시에는 여전히 키-값 파일과 함께 섞일 수 있습니다. 이 파일들은 --key 없이 푸시하세요.
  • 아무것도 일치하지 않은 범위는 실행이 이미 최신 상태라고 보고하는 대신, 일치한 항목이 없었다고 알려줍니다.

위치 기반 멤버는 범위를 지정해도 소스 텍스트를 유지합니다. 배열 요소, Android <string-array> 항목, <plurals> 수량 항목이 여기에 해당합니다. 하나를 제거하면 나머지 번호가 다시 매겨지기 때문입니다.

lockfile은 갱신되지 않습니다#

키 범위 실행은 파일의 일부만 번역하므로, lockfile의 소스 해시는 의도적으로 그대로 둡니다. 그 파일에서 바뀐 다른 내용은 여전히 보류 상태로 남아 있고, 다음 일반 lingo push에서 반영됩니다.

--force / -f#

bash
lingo push docs/en/about.md --force

기존 번역을 모두 무시하고 서버 측 캐시도 우회한 채, 일치하는 모든 대상을 다시 번역합니다. 정말로 전체 프로젝트를 다시 번역하려는 것이 아니라면, 위치 기반 패턴이나 --backfill-missing로 범위를 지정하세요. 범위 없는 lingo push --force는 구성된 모든 패턴을 다시 번역하며, 이를 막는 것은 아래 확인 절차뿐입니다.

아직 한 번도 번역된 적 없는 프로젝트에는 덮어쓸 내용이 없으므로, 여기서는 --force이 아무 역할도 하지 않습니다. 대신 --backfill-missing을(를) 사용하세요. 전반적으로도 이쪽이 더 안전한 방식입니다. 빈 부분만 채워 주고, 확인을 요청하는 프롬프트도 전혀 띄우지 않습니다.

기본적으로 --force는 실행 전에 확인을 요청합니다:

text
! --force will retranslate every target for pattern(s): docs/en/about.md and
  overwrite existing translations. Continue? (Yes, retranslate / Cancel)

프롬프트를 건너뛰려면 --yes / -y를 사용하세요(CI에 적합).

전체 파일이 아니라 몇 개의 문자열만 다시 처리하려면 --key를 사용하세요. 비용은 지정한 키에 대해서만 발생합니다.

--backfill-missing#

bash
lingo push --backfill-missing

아직 존재하지 않는 모든 대상을, 설정된 모든 패턴에 걸쳐 번역합니다. config의 모든 패턴에 대해 scoped push를 수행하는 것과 같지만, 없는 파일만 생성합니다. targetLocales에 새 로캘을 추가한 뒤나, 새 프로젝트에서 첫 push를 할 때 사용하세요.

--force와 함께 사용하면 처음부터 전체를 다시 번역할 수 있습니다:

bash
lingo push --backfill-missing --force --yes

--yes / -y#

--force 확인 프롬프트를 건너뜁니다. --force 없이는 효과가 없고, --key와 함께 써도 효과가 없습니다. 키 범위는 지정한 키에만 적용되므로 확인을 묻지 않기 때문입니다.

--estimate#

bash
lingo push --estimate
lingo push 'docs/en/**/*.md' --estimate

이번 push의 예상 비용을 출력한 뒤 번역은 수행하지 않고 종료합니다. CLI는 해싱, 델타 계산, 소스 바이트 업로드를 포함한 전체 push 파이프라인을 실행해 서버가 정확한 델타를 계산할 수 있게 한 다음, 실행을 시작하는 대신 엔진에 해당 run의 비용 산정을 요청합니다. 번역도, 결과물 기록도, 과금도 발생하지 않으며 lockfile과 대상 파일도 그대로 유지됩니다.

이 값은 견적이 아니라 예상치입니다. --estimate는 범위 지정은 물론 --key / --force / --backfill-missing와도 함께 사용할 수 있어, 지금 실행하려는 push의 비용을 정확히 가늠할 수 있습니다.

변경된 소스가 없으면 --estimate는 일반 push와 마찬가지로 ✓ Nothing to push.와 함께 즉시 종료됩니다.

같은 소스에 대한 run이 이미 진행 중이라면 --estimate는 일부만 시작된 run의 비용을 산정하는 대신 실패합니다:

text
Error: Cannot estimate: existing group run_a8c... is already in 'running' state. Change a source file or wait for the run to finish.

출력#

성공 시:

text
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에서 유용합니다:

text
✓ 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

--estimate를 사용할 때:

text
Estimating push cost…
› Estimated cost: ~$1.87 (12 target(s), ~48,000 output tokens — estimate, not a quote)
  de: ~$0.9350 (6 target(s), ~24,000 tokens)
  fr: ~$0.9350 (6 target(s), ~24,000 tokens)
  4 target(s) already up-to-date — no cost.
✓ Estimate complete — nothing was translated. Run `lingo push` to start the translation.

재시도 동작#

lockfile은 실행이 완전히 성공했을 때만 업데이트됩니다. 부분 실패(예: 한 로캘에서 타임아웃)가 발생하면 lockfile의 소스 해시는 바뀌지 않으므로, 다음 lingo push는 동일한 diff를 다시 시도합니다 — 수동으로 초기화할 필요가 없습니다.

번역이 시작되기 전에 엔진에서 오류가 발생하면(인증, 검증), 아무것도 기록되지 않고 lockfile도 변경되지 않습니다.

자주 쓰는 패턴#

CI: merge 시 번역#

yaml
- run: lingo push --backfill-missing --yes
- run: git add . && git commit -m "chore: refresh translations" && git push

--backfill-missing는 안전한 기본값입니다. 아무것도 덮어쓰지 않고, 비어 있는 부분만 채웁니다.

몇 개의 문자열만 다시 번역하기#

bash
lingo push --key auth.login --key billing.plan --wait

문구가 바뀐 뒤 해당 키만 정확히 다시 번역하고, 파일의 다른 모든 키는 그대로 둡니다.

단일 파일 반복 작업#

bash
lingo push docs/en/onboarding.md -f -y

카피를 크게 수정한 뒤 소스 파일 하나만 다시 번역합니다. 빠르게 반복 작업하려면 프롬프트를 건너뛰세요.

새 로캘 추가#

targetLocales에서 .lingo/config.json를 늘린 뒤:

bash
lingo push --backfill-missing

기존 번역은 다시 번역하지 않고, 전체 코퍼스를 새 로캘로 번역합니다.