i18n.lock 잠금 파일 - Lingo.dev CLI

i18n.lock은 콘텐츠 체크섬을 추적하여 불필요한 재번역을 방지하고 Lingo.dev CLI 성능을 최적화하는 잠금 파일입니다.

i18n.lock은 소스 콘텐츠와 번역 키의 체크섬을 저장하여 번역 실행 간 변경 사항을 식별합니다. 그 결과 새로운 콘텐츠나 수정된 콘텐츠만 번역되어 처리 시간과 번역 비용이 절감됩니다.

잠금 파일 구조

i18n.lock은 구조화된 YAML 형식을 사용하여 콘텐츠 체크섬을 저장합니다:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    key: f8692d39317193acf0e2e47172703c46
  b18975fb19122ebb67g0ef817641f553:
    key: g9703e40428204bdf1f3f58283814d57

구성 요소:

version — 마이그레이션 호환성을 위한 잠금 파일 스키마 버전
checksums — 번역된 콘텐츠를 추적하는 콘텐츠 체크섬과 키 체크섬의 맵
checksums.[content-hash] — 고유 식별자 역할을 하는 소스 콘텐츠의 SHA-256 해시
checksums.[content-hash].key — 키 이름 변경 감지를 가능하게 하는 번역 키의 SHA-256 해시

Lingo.dev CLI는 다른 키 체크섬을 가진 동일한 콘텐츠를 감지하면 기존 번역을 보존합니다. 재번역이 발생하지 않아 키 구성 변경을 허용하면서도 번역 일관성을 유지합니다. 키 이름 변경에 대해 자세히 알아보세요.

워크플로 통합

i18n.lock은 번역 워크플로 중에 자동으로 작동합니다:

첫 실행 — 초기 콘텐츠 체크섬으로 잠금 파일을 생성합니다:

npx lingo.dev@latest run
# Creates i18n.lock with all source content checksums

잠금 파일 재생성 — 잠금 파일을 처음부터 다시 생성합니다:

npx lingo.dev@latest lockfile --force
# Recreates i18n.lock with all source content checksums

팁: 병합 충돌 해결 중에 이 명령을 사용하여 잠금 파일을 실제 상태로 안전하게 재설정할 수 있습니다. 중복 제거는 각 로드 시 자동으로 실행됩니다. 잠금 파일 중복 제거를 참조하세요.

후속 실행 — 변경된 콘텐츠만 처리합니다:

npx lingo.dev@latest run
# Compares current content against i18n.lock
# Translates only new or modified content

강제 재번역 — 잠금 파일 최적화를 우회하고 모든 콘텐츠를 재번역하여 잠금 파일을 재생성합니다:

npx lingo.dev@latest run --force
# Ignores i18n.lock and retranslates all content

고정 검증 — 번역 완전성을 검증합니다:

npx lingo.dev@latest run --frozen
# Fails if any content requires translation
# Used in CI/CD to ensure complete translations

잠금 파일 중복 제거

잠금 파일 YAML은 동일한 체크섬 블록 아래에 중복된 번역 키를 포함할 수 있습니다. 표준 YAML 파서는 마지막 항목만 유지하므로 추적이 손실되고 수동으로 해결하기 어려운 병합 충돌이 발생할 수 있습니다.

Lingo.dev CLI는 일관된 잠금 파일 상태를 위해 구축되었습니다. 로드될 때마다 잠금 파일을 자동으로 중복 제거합니다. 체크섬 블록 아래의 중복 키가 감지되어 제거되며, 마지막 항목이 유지됩니다(일반적인 병합 동작과 일치하는 last-write-wins 방식). 그 결과 잠금 파일은 내부적으로 일관성을 유지하고 다시 기록되는 내용과 일치합니다.

실행 시점 — 중복 제거는 다음을 포함한 모든 로드 시 실행됩니다:

npx lingo.dev@latest run
npx lingo.dev@latest pull
npx lingo.dev@latest push
npx lingo.dev@latest status
npx lingo.dev@latest lockfile

중복 항목이 제거되면 CLI는 Removed 3 duplicate entries from i18n.lock와 같은 메시지를 기록합니다. 사용자 조치가 필요하지 않으며, 이 단계는 멱등성을 가지며 모든 로드 시 안전하게 실행됩니다. 어렵거나 반복되는 병합 문제의 경우 npx lingo.dev@latest lockfile --force를 사용하여 잠금 파일을 처음부터 다시 생성할 수 있습니다.

예시 — 동일한 키를 변경한 두 브랜치를 병합한 후:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.hello: abc123
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: ghi012
    button.submit: jkl345

로드 시 CLI는 중복을 제거하고 각 키의 마지막 항목을 유지합니다:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: jkl345

두 개의 중복 항목이 제거됩니다.

버전 관리 통합

i18n.lock은 번역 파일과 함께 버전 관리에 커밋되어야 합니다.

lockfile은 Lingo.dev CLI의 증분 번역 시스템에서 필수적인 부분으로, 모든 규모의 프로젝트에 실용적입니다.