CLI의 영구 상태는 세 곳에 저장됩니다. 프로젝트 내부 두 곳(커밋됨), 홈 디렉터리 한 곳(머신별)입니다.
.lingo/config.json — 커밋됨#
lingo init(로컬라이제이션 섹션)과 lingo link(org/엔진 바인딩)로 생성됩니다. 이 파일은 커밋하세요.
{
"orgId": "org_a8c...",
"engineId": "eng_b9d...",
"sourceLocale": "en",
"targetLocales": ["de", "fr", "es"],
"files": [
{ "pattern": "locales/en.json" },
{ "pattern": "docs/en/**/*.md" }
]
}필드 레퍼런스#
| 필드 | 필수 여부 | 설명 |
|---|---|---|
orgId | 예(link 이후) | 엔진을 소유한 조직입니다. |
engineId | 예(link 이후) | 번역을 수행하는 엔진입니다. 모델 구성, 용어집, 브랜드 보이스를 담고 있습니다. |
sourceLocale | 예 | 소스 파일의 로캘 코드입니다(예: "en"). 소스 파일은 읽기만 하며, 쓰지는 않습니다. |
targetLocales | 예 | 번역 대상 로캘입니다. 출력 파일은 소스와 같은 디렉터리에 기록되며, 패턴 내 로캘 코드만 바뀝니다(locales/en.json → locales/de.json). |
files | 예 | 소스 패턴 배열입니다. pattern은 glob입니다(슬래시 사용, ** 재귀, * 와일드카드). CLI는 대상 경로를 해석할 때 로캘 코드를 치환합니다. |
github | 아니요 | GitHub App용 설정입니다. CLI 자체에서는 무시됩니다. |
패턴 → 대상 매핑#
CLI는 패턴 안의 소스 로캘을 각 대상 로캘로 바꿉니다.
locales/en.json→locales/de.json,locales/fr.json, ...docs/en/**/*.md→docs/de/**/*.md(하위 트리 미러링)copy/en/marketing.md→copy/de/marketing.md
소스 레이아웃 경로에 로캘 코드가 없다면 구조를 바꿔야 합니다. 그 정보가 없으면 CLI는 대상 파일의 위치를 추론할 수 없습니다.
.lingo/lock.json — 커밋됨#
모든 소스 및 대상 파일의 마지막으로 확인된 서버 해시를 추적합니다. 용도는 두 가지입니다.
- **
lingo push**은 마지막으로 성공한 실행 이후 소스가 바뀌었는지 판단할 때 이를 참조합니다. 변경되지 않은 파일은 서버와 다시 통신하지 않고 no-op으로 처리됩니다. - **
lingo pull**은 로컬 대상 파일의 수정 여부를 감지할 때 이를 참조합니다. 로컬 대상의 해시가 lockfile 값과 다르면 pull 시 로컬 작업이 덮어써지므로,--force없이 실행하면pull에서 오류가 발생합니다.
소스 해시는 push가 완전히 성공한 뒤에만 lockfile에 커밋되므로, 중간에 끝난 실행도 수동 정리 없이 다시 시도할 수 있습니다.
번역된 출력과 함께 lockfile도 커밋하세요. 충돌이 나면 package-lock.json 충돌을 다루듯 처리하면 됩니다. lingo push를 다시 실행해 재생성하세요.
~/.lingo/runs/<hash>.json — 머신별#
가장 최근에 제출한 push를 기록해 lingo pull가 어떤 실행의 출력을 가져와야 하는지 알 수 있게 합니다. 터미널을 닫았다 다시 열어도, 같은 체크아웃을 공유하는 여러 머신에서도 동작합니다.
{
"runId": "run_a8c...",
"engineId": "eng_b9d...",
"organizationId": "org_a8c...",
"sourceLocale": "en",
"createdAt": "2026-05-22T14:32:01.000Z"
}파일명 해시는 파일 내용이 아니라 프로젝트 루트의 절대 경로를 기준으로 만들어지므로,
en.json을 수정해도 이 파일은 무효화되지 않습니다. 같은pull는 계속 해당 실행을 찾을 수 있습니다.- 같은 머신에서 동일한 리포지토리를 두 번 체크아웃하면 서로 다른 파일이 생성됩니다(절대 경로가 다르기 때문입니다).
- push와 pull 사이에 프로젝트를 옮기면(
mv ~/Projects/foo ~/Projects/bar) 해시가 바뀌어 조회가 무효화됩니다. 실행 ID를 수동으로 복구해야 한다면 JSON은 여전히~/.lingo/runs/에 남아 있습니다.
이 파일은 프로젝트 상태가 아니라 머신별 상태입니다. 리포지토리 바깥에 있으므로 gitignore 대상도 아닙니다.
인증 자격 증명 — ~/.lingo/auth.json#
lingo login에서 저장합니다(OTP 플로는 Supabase 세션을 저장하고, --api-key 플로는 키를 저장합니다). 커밋되지 않으며, CLI 자체 외에는 어떤 것도 이 파일을 읽지 않습니다.
lingo logout # clear credentials
lingo whoami # check what's stored and which org/engine the cwd resolves to하위 디렉터리에서의 해석#
모든 명령은 cwd에서 시작해 가장 가까운 .lingo/config.json를 찾을 때까지 상위 디렉터리로 올라갑니다. src/components/에서 lingo push를 실행해도 lockfile은 components/ 안에 새 .lingo/를 만드는 대신 프로젝트 루트에 기록됩니다. 따라서 명령을 실행할 때마다 루트로 cd할 필요는 없습니다.
