lingo extract
명시적으로 작성한 번역 호출에서 원본 JSONC와 타입스크립트 선언을 생성합니다.
lingo extract는 명시적으로 작성한 리액트 메시지에 카탈로그 식별자를 부여합니다. 타입스크립트/TSX 호출을 스캔해 원본 JSONC와 선언을 로컬에 저장하고, 각 항목을 소스와 연결하는 메타데이터를 보존합니다. 임의의 JSX를 다시 작성하거나 번역을 요청하지는 않습니다.
설정을 마친 리액트 컴포넌트에서는 다음과 같은 호출을 지원합니다.
const l = useLingo();
const label = l.text("Place order", { context: "Checkout submit button" });프로젝트 루트에서 추출을 실행하세요.
lingo extract --src src --source-locale en기본 경로를 사용한다면 locales/en.jsonc와 lingo.d.ts를 확인하세요. 원본 카탈로그에는 메시지 값, 컨텍스트, 소스 위치가 기록됩니다. 리액트 빠른 시작에서는 컴포넌트에 필요한 가져오기 구문과 프로바이더 설정을 안내합니다.
옵션 #
| 옵션 | 기본값 또는 동작 |
|---|---|
--src <path> | 스캔할 디렉터리. 기본값은 src. |
--source-locale <locale> | 출력할 원본 로캘. 기본값은 en. |
--out <path> | 이 옵션, 설정된 i18n.messagesPath, 기본값 locales 순으로 우선 적용. |
--types <path> | 이 옵션, 설정된 i18n.typesPath, 기본값 lingo.d.ts 순으로 우선 적용. |
--check | 파일을 쓰지 않고 생성된 바이트와 디스크에 저장된 바이트를 비교. |
경로는 가장 가까운 프로젝트 루트를 기준으로 해석됩니다. 원본 로캘은 현지화 설정의 sourceLocale를 상속하지 않으므로, 다른 언어를 사용하려면 명시적으로 지정하세요. 일반 쓰기 작업 시에는 선언 파일을 저장할 디렉터리가 생성됩니다.
스캐너가 인식하는 항목 #
스캐너는 useLingo 또는 createLingo의 반환값이 할당된 변수의 text, rich, plural, select 호출과 관례적으로 사용하는 l 및 .l 수신 객체를 인식합니다. 문자열 리터럴, 표현식이 없는 템플릿, 정적 형식 객체를 지원합니다.
동적 메시지에는 안정적으로 추출할 수 있는 원본이 없습니다. 팩터리 반환값을 구조 분해하면 추적하던 수신 객체의 형태가 사라져 경고가 발생합니다. 선언 파일, 점으로 시작하는 파일과 디렉터리, node_modules는 제외됩니다. TS/TSX 파일이 없으면 추출 작업은 이를 알리고 결과 없이 종료됩니다. 프로세스가 정상적으로 종료되었다고 해서 메시지를 찾았다는 뜻은 아닙니다.
식별자와 병합 동작 검토 #
키는 원본과 컨텍스트를 바탕으로 생성됩니다. 문구나 컨텍스트가 바뀌면 새 식별자가 생성될 수 있지만, 런타임에 대입되는 값은 식별자에 영향을 주지 않습니다. 키가 충돌하면 추출에 실패하므로, 항목을 구분할 수 있도록 컨텍스트를 추가해야 합니다.
추출 결과는 기존 원본 카탈로그와 병합됩니다. 현재 값은 보존하고, 컨텍스트와 소스 메타데이터는 갱신하며, 새 항목은 추가하고, 더 이상 발견되지 않는 메시지는 미사용 항목으로 표시합니다. 출력은 정렬되며 동일한 입력에는 항상 동일한 결과가 생성됩니다. 미사용 항목이 애플리케이션에서 의도적으로 제거된 것이라고 판단하기 전에 경고를 확인하세요.
카탈로그 확인 또는 번역 #
lingo extract --check는 파일을 쓰지 않고 카탈로그와 선언의 바이트를 모두 비교합니다. lingo check는 컨텍스트, 미사용 항목, 발견된 대상까지 추가로 검사합니다.
번역하려면 실제 .jsonc 경로를 files[]에 추가하고 인증과 연결을 마친 뒤, 최초 실행 시 lingo push --backfill-missing --wait를 사용하세요. 이후 변경 사항은 일반 푸시로 전송합니다. 추출 경로를 바꿔도 파일 설정은 자동으로 변경되지 않습니다.
JSONC 호환 로더와 카탈로그 메타데이터 정책을 사용해 결과를 불러오세요. 프로바이더에는 문자열 맵이 필요합니다. 파일 경로를 그대로 전달하거나 일반적인 JSON 가져오기를 사용하는 것만으로는 이 변환이 완료되지 않습니다.