Lockfile과 캐시
업데이트와 복구 과정에서도 소스 기준 상태, 대상 해시, 원격 아티팩트, 로컬 실행 포인터 간의 연결을 유지하세요.
증분 번역을 하려면 무엇이 바뀌었는지 알아야 합니다. .lingo/lock.json는 소스와 대상의 해시를 기록하고, 서버는 아티팩트와 번역 결과를 보관하며, 홈 디렉터리에 저장된 로컬 포인터는 수집할 최신 실행을 식별합니다. 각각 용도가 다르므로, 하나를 삭제하는 것이 다른 항목의 문제까지 해결하는 만능 복구 방법은 아닙니다.
프로젝트 기준 상태 #
Lockfile은 버전 1을 사용하며, 저장소 기준 상대 경로를 SHA-256 해시에 연결하는 files 맵을 포함합니다:
{
"version": 1,
"files": {
"locales/en.json": {
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
}
}이 해시는 형식을 보여 주기 위한 예시이며, 복사해서 사용할 값이 아닙니다. 소스 해시는 증분 비교에 필요한 이전 바이트를 식별합니다. 대상 해시는 수집 전에 로컬 수정 사항을 감지하는 데 쓰입니다. 이 파일에는 번역문이나 품질 평가가 들어 있지 않습니다.
Lockfile은 그 안에 기록된 확정 소스 및 대상 변경 사항과 함께 커밋하세요. 상태 정보가 없으면 푸시는 최초 기준 상태를 설정하는 방식으로 동작합니다. 상태 정보의 형식이 잘못되었거나 지원되지 않으면, 알림 없이 초기화하는 대신 실패합니다.
해시가 갱신되는 시점 #
수집하면 완료된 대상의 해시가 기록됩니다. 수집 없이 제출만 해서는 기준 상태가 확정되지 않습니다. 각 문서는 개별적으로 확정되며, 해당 문서의 모든 대상이 완료될 때까지 같은 문서에 속한 대상의 확정이 보류됩니다. 기존의 전체 소스 기준 상태는 문서에 설정된 모든 대상 로캘이 포함되고, 모든 대상이 완료되었으며, 키 범위가 지정되지 않았을 때만 갱신됩니다. 일부 로캘만 수집하면 나머지 로캘에는 기존 기준 상태가 유지됩니다. 소스 항목이 없다면 이 과정에서 초기화할 수 있습니다. 키 새로고침 시에는 push --wait와 풀 중 어느 방식으로 수집하든 소스 해시가 바뀌지 않습니다.
아티팩트와 캐시된 번역 #
아티팩트는 콘텐츠 주소 지정 방식으로 저장되므로, 푸시할 때 서버에 없는 바이트만 업로드합니다. Lockfile이 가리키는 이전 소스는 로컬 바이트나 서버에서 복구할 수 있어야 합니다. 어느 쪽에도 없다면 해당 Lockfile 항목을 확인하고, 정상임이 확인된 바이트나 일관된 기준 상태를 복구하세요. 추측한 해시로 대체하지 마세요.
번역 결과 캐시는 소스 저장소와는 별개입니다. 로컬 대상 파일을 삭제한다고 해서 이후 요청에서 모델을 새로 호출하는 것은 아닙니다.
최신 실행 포인터 #
~/.lingo/runs/<project-hash>.json는 프로젝트 루트의 절대 경로를 기준으로 가장 최근 푸시를 식별합니다. 실행, 조직, 로컬라이제이션 엔진의 ID와 소스 로캘, 생성 시각이 여기에 포함됩니다. 해당 푸시를 수집하기 전까지는 요청 식별 정보도 보관하므로, 푸시를 반복해도 중복 제출하지 않고 기존 제출을 재사용할 수 있습니다.
이 포인터는 .lingo/run.json가 아니며 Git으로 함께 전달되지 않습니다. 위치를 옮긴 checkout이나 다른 실행기에는 설정과 Lockfile이 같아도 포인터가 없을 수 있습니다. 새로 푸시하면 포인터가 대체될 수도 있습니다. 가져오기가 끝날 때까지 원래 실행의 식별 정보를 비밀 정보가 아닌 운영 기록에 보관하세요.
다른 CI 작업을 위한 실행 보존 #
검토를 기다려야 하거나 제출과 가져오기를 별도 작업으로 나누는 경우, 제출에 사용한 실행기가 사라지기 전에 포인터를 보존하세요. 제출 직후, 다른 푸시를 하기 전에 사용할 .lingo/config.json가 있는 디렉터리의 절대 경로에서 다음 명령을 실행하세요:
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
const root = process.cwd();
if (!existsSync(".lingo/config.json")) throw new Error("Run from the configured project root");
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
mkdirSync(".lingo-ci", { recursive: true });
copyFileSync(join(homedir(), ".lingo", "runs", `${hash}.json`), ".lingo-ci/run.json");
writeFileSync(".lingo-ci/project-root.txt", root);
JS이 두 파일에는 비밀 정보가 아닌 실행 포인터와, 해당 포인터를 찾는 데 사용한 정확한 프로젝트 루트 절대 경로가 들어 있습니다. 내보낸 JSON의 runId가 이번 제출에서 출력된 ID와 일치하는지 확인하세요. 새 실행을 기록하기 전에 제출이 실패하면 이전 포인터가 남아 있을 수 있습니다. 확인을 마친 파일은 소스 리비전, .lingo/config.json, .lingo/lock.json, 그에 맞는 소스 및 대상 파일과 함께 접근이 제어되는 작업 아티팩트로 보관하세요. 커밋하지 않은 결과도 포함해야 합니다. 단일 파일 CI 예시에서는 locales/en.json와 locales/es.json를 보관하세요. 다른 프로젝트에서는 실제로 선택한 경로를 사용하세요. 소스와 대상이 하나의 파일을 공유한다면 공유 카탈로그 전체를 보존하세요. 검토와 수집을 마칠 수 있도록 아티팩트 보존 기간을 충분히 길게 설정하세요. ~/.lingo 전체, 자격 증명 파일, 비밀 환경 변수 값은 절대 아카이브에 포함하지 마세요.
검토가 끝나면 권한이 있는 실행기의 동일한 프로젝트 루트 절대 경로에 같은 리비전과 보관한 파일 상태를 복원하세요. 동일한 CLI 버전을 설치하고, 자격 증명은 실행기의 비밀 정보 관리 기능을 통해 별도로 제공하세요. 해당 루트에서 다음 포인터만 복원하세요:
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
const root = readFileSync(".lingo-ci/project-root.txt", "utf8");
if (process.cwd() !== root || !existsSync(".lingo/config.json")) {
throw new Error("Restore the configured project at its original absolute root");
}
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
const directory = join(homedir(), ".lingo", "runs");
mkdirSync(directory, { recursive: true });
const destination = join(directory, `${hash}.json`);
if (existsSync(destination)) throw new Error("Preserve the existing run pointer before replacing it");
copyFileSync(".lingo-ci/run.json", destination);
JS
lingo pull --dry-run표시된 실행이 보존한 실행과 일치하는지 확인하고 충돌을 해결한 다음, lingo pull를 사용해 가져온 결과를 확인하세요. 먼저 푸시하면 포인터가 대체되므로 푸시하지 마세요. CI 서비스에서 원래 루트 경로를 재현할 수 없다면, 해당 경로를 사용하는 권한 있는 영구 실행기에서 제출과 가져오기를 수행하세요. 다른 위치의 checkout에 포인터를 복사하는 것만으로는 충분하지 않습니다. 수집과 운영상 보관이 모두 끝난 후에만 임시 .lingo-ci 내보내기 파일을 삭제하고, 번역 커밋에는 포함하지 마세요.
기존 번역과 사람이 수정한 내용 #
범위 지정 또는 부트스트랩 계획에서는 기존 대상을 채택할 수 있습니다. 먼저 언어와 완성도를 확인하세요. 소스 언어로 된 임시 문구는 번역이 아니어도 존재 여부 검사를 통과할 수 있습니다. 백필은 누락된 일반 파일을 생성할 뿐, 기존 파일 안의 누락된 키를 추가하지는 않습니다.
일반적인 증분 작업에서는 소스 키가 바뀌지 않은 대상의 수정 사항을 보존할 수 있도록 전달합니다. 소스 키가 바뀌면 해당 수정 사항이 대체될 수 있습니다. JSON은 키 경로를 식별자로 사용하므로, 소스 문구가 같아도 키 이름을 바꾸면 새 작업이 생성됩니다. 이는 v0의 콘텐츠 지문 재사용 방식과 다릅니다.
preservedKeys는 대상 텍스트를 최종 기준으로 유지해야 할 때 명시적으로 보호하는 기능입니다. 다만 파일 전체를 강제 처리하면 이 기능에 필요한 현재 대상의 맥락이 사라집니다. 풀은 쓰기 전에 최신 해시를 비교하며, Git 커밋만으로는 이 비교 결과가 달라지지 않습니다. push --wait로 직접 수집하는 동안에는 대상을 수정하지 마세요.
브랜치와 공동 쓰기 작업 #
| 방식 | 영향 |
|---|---|
| 기능 브랜치에서 번역 | 소스와 대상을 함께 검토하고, 리베이스 과정에서 충돌하는 기준 상태 변경 사항을 조정합니다. |
| 소스 병합 후 번역 풀 리퀘스트 생성 | 검토를 별도로 진행하므로 번역 변경 사항이 반영되기까지 시간 간격이 생깁니다. |
| GitHub App 번역 풀 리퀘스트 | 연동 기능이 트리거와 결과 반영을 제어하며, 실행 승인은 병합과 별개입니다. |
| 권한이 있는 실행기가 브랜치에 직접 쓰기 | 명시적인 쓰기 권한, 콘텐츠 검사, 동시 쓰기 방지 장치가 필요합니다. |
Lockfile 병합 충돌이 발생하면 먼저 양쪽이 각각 어떤 소스 및 대상 리비전을 나타내는지 확인하세요. 확정할 콘텐츠를 조정한 다음, 적절한 워크플로를 통해 일관된 기준 상태를 유지하거나 재구성하세요. 서로 관련 없는 해시를 합치거나 충돌을 없애려고 Lockfile을 삭제하면 미완료 번역이 가려질 수 있습니다.
제공업체 설정은 GitHub App, GitHub Actions, GitLab, Bitbucket 또는 빌드카이트에서 다룹니다. 검사는 설정된 소스를 이 Lockfile과 비교해 누락된 대상 파일을 알려줍니다. 리액트 .jsonc 카탈로그가 아닌 경우 파일 내부의 키는 확인하지 않습니다.
홈 디렉터리의 기타 로컬 상태 #
~/.lingo/update-check.json는 버전 확인 결과를 24시간 동안 캐시합니다. 자격 증명과 익명 원격 측정 식별 정보는 별도로 저장됩니다. 어느 것도 번역된 파일 결과를 보관하지 않습니다. 상태 정보를 삭제하기 전에 문제 해결을 참고해 어떤 작업이 실패했는지 확인하세요.