Lingo check

번역이 최신 상태가 아니면 CI를 실패시키고, React 카탈로그까지 검사합니다.

lingo check은(는) 번역이 최신 상태가 아니면 실패합니다. 각 소스 파일을 .lingo/lock.json와(과) 비교하고, 모든 대상 파일이 있는지 확인하며, @lingo.dev/react 프로젝트에서는 추출된 카탈로그, 선언, 컨텍스트, 번역까지 검사합니다.

sh
lingo check --json

어떤 검사가 실행되나요? #

검사실행 조건
파일 검사.lingo/config.json에 files이(가) 있거나, React 프로젝트가 아닌 경우
React 검사루트 package.json 또는 --src에 가장 가까운 파일에 @lingo.dev/react, @lingo.dev/react-next, @lingo.dev/react-tanstack 중 하나가 나열되어 있거나, 생성된 선언 파일(기본값 lingo.d.ts)이 있는 경우

files이(가) 있는 React 프로젝트에서는 두 검사가 모두 실행됩니다. 어떤 files 패턴과도 일치하는 파일이 없으면 lingo push와(과) 마찬가지로 no-source-files 오류와 함께 검사가 실패합니다. 단, React 프로젝트에서는 React 검사만 실행되고 그 사실이 stderr에 표시됩니다. files도 없고 React 프로젝트도 아니라면 lingo push와(과) 같은 구성 오류로 실패합니다.

lingo check은(는) API 키가 필요 없고 아무것도 쓰지 않습니다. DO_NOT_TRACK=1(으)로 끌 수 있는 CLI 원격 분석을 제외하면 네트워크 호출도 전혀 하지 않습니다. 문제를 하나라도 보고하거나 구성 오류(예: 대상 충돌, 손상된 lockfile)가 발생하면 1로, 그 외에는 0으로 종료합니다.

파일 검사 #

소스는 lingo push이(가) 전송할 파일이고, 대상은 구성된 모든 대상 로캘에 대해 푸시가 쓰게 될 경로입니다.

상황문제해결 방법
소스가 lockfile 항목과 일치하고 대상 파일이 있음없음
어떤 files 패턴과도 일치하는 파일이 없음no-source-filesfiles 패턴 수정
마지막 번역 이후 소스가 변경됨source-changedlingo push --wait, 푸시가 아직 진행 중이라면 lingo pull
소스에 해당하는 lockfile 항목이 없음source-not-pushedlingo push --wait
대상 파일이 없지만 소스는 최신 상태임missing-targetlingo push --backfill-missing --wait
대상 파일이 없고, 소스가 변경되었거나 한 번도 푸시되지 않음missing-targetlingo push --wait
대상 파일을 직접 수정함없음
lockfile이 없고 모든 대상 파일이 있음없음(stderr에 안내 표시)
lockfile이 없고 대상 파일이 없음missing-target(stderr에 안내 표시)lingo push --backfill-missing --wait 실행 후 대상 파일과 .lingo/lock.json 커밋

더 이상 구성된 소스가 아닌 경로의 lockfile 항목은 무시됩니다. lingo push이(가) 출력하는 대상 추정 경고와 YAML 건너뜀 경고도 이곳 stderr에 똑같이 표시됩니다.

문제 해석하기 #

유형살펴볼 해결 방법
missing-context추출된 메시지에 도움이 되는 컨텍스트를 추가합니다.
stale-jsonc소스 카탈로그를 다시 생성한 뒤 확인합니다.
stale-types선언을 다시 생성하고 애플리케이션의 타입 검사에 포함합니다.
missing-translation비어 있지 않은 활성 대상 값이 없는 활성 키를 확인합니다.
orphaned정리하기 전에 메시지가 실제로 제거된 것인지, 추출 과정에서 누락된 것인지 판단합니다.

파일 검사 문제와 해결 방법은 파일 검사를 참고하세요.

JSON 출력 #

JSON 출력에는 issues와(과) stats이(가) 포함됩니다. 사람이 읽기 쉬운 출력에도 같은 문제가 나열되어 로컬에서 편하게 확인할 수 있습니다.

각 문제에는 type와(과) message이(가) 있습니다. React 문제에는 src이(가) 있을 수 있고, 파일 문제에는 file이(가) 있으며, missing-target 문제에는 locale도 함께 포함됩니다.

통계에는 messages, locales, missingContext, missingTranslations, orphaned, staleJsonc, staleTypes이(가) 포함되며, React 검사가 실행되지 않았다면 0 또는 false로 표시됩니다. 로캘 수는 발견된 대상과 소스를 합한 값입니다. 파일 검사가 실행된 경우 stats.files에는 lockfile, sources, locales, changedSources, missingTargets이(가) 포함됩니다. 이 값들은 일관성을 보여 줄 뿐, 측정된 언어 품질을 나타내지는 않습니다.

CI에서 실행하기 #

포크에서 올라온 요청을 포함해 모든 풀 리퀘스트와 머지 리퀘스트에서 실행하세요.

yaml
- uses: actions/checkout@v4
- run: npx @lingo.dev/cli@latest check

추출과 동일한 입력 사용하기 #

--src, --out, --types, --source-locale은(는) React 검사에만 적용됩니다. --src의 기본값은 src, --source-locale의 기본값은 en입니다. 카탈로그 경로는 --out이(가) 구성값보다 우선하고, 그다음이 locales입니다. 선언 경로는 --types이(가) 구성값보다 우선하고, 그다음이 lingo.d.ts입니다. 경로는 프로젝트 루트를 기준으로 해석됩니다. 소스 로캘 기본값은 현지화 구성과 별개입니다. --json의 기본값은 false이며 두 검사 모두에 적용됩니다.

오래된 항목을 바로잡으려면 같은 입력으로 추출을 실행하세요. 경고와 변경 사항을 확인한 뒤 검사와 애플리케이션 빌드를 다시 실행합니다. 더 이상 쓰이지 않는 것이 확실한 항목만 정리하고, 정리한 뒤에는 선언을 다시 생성하세요.

제한 사항 #

  • 파일 검사는 파일 단위로 동작합니다. 따라서 기존 대상 파일 안에 누락된 키는 React .jsonc 카탈로그를 제외하면 보고되지 않습니다.
  • .xcstrings 파일처럼 하나의 공유 카탈로그 안에 들어 있는 로캘은 검사되지 않으며, 그 안을 직접 수정하면 소스가 변경된 것으로 간주됩니다.
  • CLI에서 GitHub App으로 전환한 저장소라면 .lingo/lock.json을(를) 삭제해야 합니다.
  • 두 소스가 같은 대상으로 해석되거나 lockfile이 손상된 경우 같은 구성 오류가 발생하면, JSON 없이 stderr에 메시지를 출력하고 1로 종료합니다.
  • 소스 해시는 바이트 단위로 정확히 비교되므로, lingo push을(를) 실행한 checkout과 CI의 checkout은 같은 줄 끝 문자를 사용해야 합니다. .gitattributes에 * text=auto eol=lf을(를) 추가하세요.

React 카탈로그의 경우 대상은 카탈로그 디렉터리 안의 .jsonc 파일입니다. files 패턴이 소스 카탈로그(예: locales/en.jsonc)와 일치하면, 구성된 모든 대상 로캘 파일도 반드시 있어야 합니다.

추출 경고 중 컨텍스트 누락 경고만 컨텍스트 문제로 처리됩니다. 동적 표현식 경고와 충돌 정보는 여기서 모든 실패를 빠짐없이 걸러내는 기준이 아니며, 충돌로 인한 실패는 추출 단계에서 직접 처리합니다. 또한 비어 있지 않은 소스 언어 자리 표시자는 실제 번역이 아니어도 존재 여부 검사를 통과할 수 있습니다.

생성된 바이트가 최신인지만 확인하면 된다면 extract --check을(를) 사용하세요. 네이티브 형식 유효성 검사와 콘텐츠 검토는 이 검사기와 함께 계속 진행하세요. 검사를 통과했다고 해서 실제 검사 범위를 벗어나는 Android 리소스, Markdown 렌더링, 번역의 의미까지 보장되는 것은 아닙니다.