CLI 문제 해결

유용한 상태 정보를 지우지 않고 파일 선택, 기준 상태, 수집, 카탈로그 문제를 해결하세요.

문제를 진단할 때는 설치된 버전, 실행한 명령어, 작업 디렉터리, 오류 내용, 영향을 받는 경로를 확인할 수 있도록 준비해 두세요. 로그를 공유하기 전에는 자격 증명을 가리세요. 시작 및 실패 진단 정보에 명령줄 인수 원문이 포함될 수 있습니다.

일치하는 소스 파일이 없음 #

가장 가까운 .lingo/config.json을 찾으세요. 하위 디렉터리에서 실행한 명령어가 상위 디렉터리의 프로젝트를 사용할 수 있습니다. 포함 설정은 비어 있어도 pattern보다 우선하므로 include부터 확인하세요. 제외 설정은 항목별로 적용되므로 다른 항목에서 같은 파일을 선택할 수도 있습니다.

docs/en/**/*처럼 지원되는 매처 구문을 사용하고, 셸 패턴은 따옴표로 묶고, 접미사 지원 여부를 확인하세요. YAML에는 yaml, yaml-root-key 또는 yaml-openapi를 명시해야 하며, 안드로이드 XML에는 android가 필요합니다. .txt, .csv 또는 .properties 파일에는 해당 확장자로 끝나는 패턴이나 "format": "txt", "format": "csv", "format": "properties" 중 하나가 필요합니다. docs/en/**/*처럼 범위가 넓은 패턴은 해당 파일을 건너뛰며, txt, csv 또는 properties 항목은 해당 확장자가 없는 모든 파일을 건너뜁니다. 형식을 명시해도 모든 확장자가 허용되는 것은 아닙니다.

출력이 잘못된 위치에 저장됨 #

경로 도출 경고를 확인하고 대상 경로를 애플리케이션 로더가 사용하는 경로와 비교하세요. 소스 로캘에 해당하는 경로 구간이 인식되지 않으면 로캘을 삽입하는 대체 방식에 의존하지 말고 targetPath 및 sourceRoot를 정의하세요. 대상 파일은 소스 검색 범위 밖에 두고 경로 충돌이 있는지 확인하세요.

파일을 옮기는 것만으로는 기준 상태가 갱신되지 않습니다. 엑스씨스트링스는 설계상 하나의 공유 소스 카탈로그를 사용하므로 일반적인 로캘별 파일 구조와는 다릅니다. 출력 경로를 참고하세요.

옵션이 적용되지 않음 #

알 수 없는 루트 및 파일 키는 경고가 표시된 뒤 무시됩니다. 철자가 맞는지, 선택한 처리기가 해당 옵션을 실제로 지원하는지 확인하세요. 카탈로그 경로 설정은 푸시 패턴을 갱신하지 않으며, 추출과 검사는 각각 소스 로캘의 기본값을 en으로 설정합니다.

로컬 점수 산정에는 프로젝트의 제이슨이 아니라 실행 가능한 lingo.config.ts을 사용합니다. 제이슨 보호 옵션이 마크다운이나 다른 형식에도 적용되는 것은 아닙니다.

기준 상태 산출물이 없음 #

잠금 해시가 가리키는 이전 소스 산출물이 로컬이나 서버에 있어야 합니다. 해당 항목을 살펴보고 정상임이 확인된 바이트 데이터나 일관된 기준 상태를 복구하세요. 오류를 숨기려고 해시를 임의로 만들거나 잠금 정보 전체를 지우지 마세요.

상태 정보가 없으면 일반적인 첫 푸시는 소스 바이트 데이터를 저장합니다. 누락된 일반 대상 파일은 보충 작업이 필요합니다. 각 작업에 어떤 기록이 필요한지는 Lockfile 및 캐시에서 확인하세요.

풀에서 충돌이 보고됨 #

lingo pull --dry-run을 실행해 쓰기 여부가 어떻게 결정되는지 확인하세요. 대상이 서버 출력, 푸시 시점에 저장된 바이트 데이터, 잠금 해시와 모두 다르면 쓰기가 차단됩니다. 해당 파일을 커밋해도 비교 결과는 달라지지 않습니다.

수정 내용을 보존해 조정하거나, 정상임이 확인된 버전으로 복원하거나, 의도적으로 교체할 때만 강제 옵션을 사용하세요. push --wait에는 풀과 달리 최신 상태를 기준으로 한 충돌 검사가 없으므로 실행 중에는 대상 파일을 수정하지 마세요.

작업이 실패했거나 완료되지 않음 #

대상별 오류를 확인하고 대기 중인 작업, 검토, 실패, 출력 누락을 구분하세요. 실행이 실패하면 push --wait과 풀은 완료된 문서를 파일로 저장한 뒤 0이 아닌 종료 코드로 종료됩니다. 상태와 실제 파일을 모두 확인하세요.

미완료 대상이 모두 사람이 하는 검토를 기다리는 상태라면 push --wait과 풀은 대기를 중단하고 그 사실을 알립니다. 모든 로캘의 작업이 끝난 문서는 수집할 수 있습니다. 검토자가 검토를 마치면 lingo pull를 다시 실행하세요. 다시 푸시해도 검토 대기 상태는 해소되지 않습니다.

실행이 실패했다면 보고된 원인을 해결하고 해당 작업에 맞는 명령어를 다시 실행하세요. 일반적인 소스 갱신에는 소스를 그대로 두고 기준 상태를 유지한 채 lingo push --wait을 사용하세요. 대상 파일이 누락된 경우에는 언어 추가에 따라 기존 대상을 모두 최신 상태로 만든 뒤 누락 파일 보충 작업을 다시 실행하세요. 단순히 재시도를 요청하기 위해 소스를 수정하거나 강제 옵션을 사용하거나 상태 정보를 삭제할 필요는 없습니다.

푸시는 제출하거나 다시 연결한 작업의 식별자를 출력합니다. 이전 푸시의 결과를 아직 수집하지 않았고 요청이 바뀌지 않았다면 푸시는 해당 요청을 재사용합니다. 실행 중인 작업은 식별자를 유지하고, 실패한 작업은 새 작업으로 대체됩니다. 실패한 작업의 식별자를 보관하고 다음에 출력되는 Job 줄의 식별자가 달라졌는지 확인하세요. 식별자가 달라졌다는 것은 새 작업이 제출되었다는 뜻이지 번역이 성공했다는 뜻은 아닙니다. 대상별 결과를 확인하고 출력을 가져온 뒤 변경 사항을 검토하세요. --wait 실행 중에는 로컬 대상을 변경하지 마세요. 로컬 수정 내용을 보호해야 한다면 푸시와 충돌 검사가 적용되는 풀을 따로 실행하세요.

설치된 클라이언트가 같은 실패 작업을 반환한다면 반복 제출을 중단하고 support@lingo.dev으로 이메일을 보내세요. CLI 버전, 민감한 정보를 제거한 명령어, 이전 실행과 반환된 실행의 식별자, 소스 리비전, 영향을 받는 로캘과 경로, 타임스탬프, 민감한 정보를 가린 오류 내용을 포함하세요. 자격 증명, 비공개 소스 텍스트, 자격 증명 파일 원본은 메시지에 포함하지 마세요. 문제를 조사하는 동안 로컬 실행 포인터와 Lockfile을 보존하세요.

실행 포인터를 삭제한다고 해서 새 번역을 확실히 요청할 수 있는 것은 아닙니다. 푸시 결과를 수집하기 전까지 포인터는 중복 제출을 방지하는 요청 식별 정보를 보관합니다. 실행을 찾을 수 없다면 사용 중인 컴퓨터와 프로젝트 루트의 절대 경로를 확인하고, 다른 푸시가 포인터를 교체하지 않았는지 살펴보세요.

카탈로그 검사 실패 #

검사할 때와 동일한 로캘과 경로로 추출하세요. 고아 항목을 제거하기 전에 동적 호출 및 구조 분해된 호출에 관한 경고를 확인하세요. 대상 파일 누락은 files 패턴이 소스 카탈로그와 일치할 때만 보고됩니다. 그렇지 않으면 예상 로캘과 기존 파일을 비교하세요.

의도적으로 제거한 항목만 정리하고 선언을 다시 생성한 뒤 검사와 애플리케이션 빌드를 실행하세요. status은 검사로 이동했습니다. 내부 서비스 이름은 실행 가능한 명령어가 아닙니다.

삭제하기 전에 #

완전 삭제는 대상 파일의 삭제 결과를 미리 보여 줍니다. 파일 및 로캘 필터를 사용하면 선택한 대상과 해당 Lockfile 항목만 삭제됩니다. 필터 없이 완전 삭제를 실행하면 Lockfile 전체가 제거됩니다. 공유 엑스씨스트링스 카탈로그는 건너뜁니다. 삭제 자체가 목적일 때 완전 삭제를 사용하세요. 대부분의 복구 작업은 승인된 문구와 복구 가능한 상태를 유지하면서 문제가 있는 부분만 바로잡으면 됩니다.