CLI 옵션

translate-docs 캐시 동작, 플래그, 배치 프롬프트 형식 및 내부 SQLite 경로 키에 대한 참조입니다.

캐시 동작 및 translate-docs 플래그

CLI는 SQLite에 파일 추적 정보(파일 × 로케일별 소스 해시)와 세그먼트 행(번역 가능 청크당 해시 × 로케일)을 유지합니다. 일반 실행 시 추적된 해시가 현재 소스와 일치하고, 출력 파일이 이미 존재하며, 그리고 출력 파일의 수정 시간이 소스 파일보다 최소한 같거나 더 최근인 경우 파일 전체를 건너뜁니다. 그렇지 않으면 파일을 처리하고 세그먼트 캐시를 사용하여 변경되지 않은 텍스트는 API를 호출하지 않습니다. 저장된 텍스트가 스크립트 검증에 실패하면 세그먼트 캐시 적중도 거부됩니다. 예상되는 문자 체계가 있는 로케일(hi, ja, zh-Hans, ar, …)에 대해 --check-cache를 사용하여 파일 수준 건너뛰기를 우회하면, --force-update 없이 로마자화되거나 잘못된 문자 체계의 캐시 행을 재시도할 수 있습니다.

플래그	효과
(기본값)	추적 + 디스크상 출력이 일치할 때 변경되지 않은 파일을 건너뛰고, 나머지에는 세그먼트 캐시를 사용합니다. 잘못된 문자 체계의 캐시 적중은 처리되는 파일에 대해서만 거부되고 재번역됩니다.
-l, --locale <codes>	쉼표로 구분된 대상 로케일(생략된 경우 기본값은 루트 targetLocales 및 각 docs[] 블록의 선택적 targetLocales의 합집합과 일치합니다).
-p, --path / -f, --file	이 경로 아래에서만 markdown/JSON을 번역합니다 (프로젝트 상대, 절대 또는 glob 패턴); --file는 --path의 별칭입니다.
--dry-run	파일 쓰기 및 API 호출 없음.
--type <kind>	markdown 또는 json로 제한(구성에서 활성화된 경우 둘 다가 기본값).
--json-only / --no-json	JSON 레이블 파일만 번역하거나, JSON은 건너뛰고 마크다운만 번역합니다.
-j, --concurrency <n>	최대 병렬 대상 로케일 수 (기본값은 설정 또는 CLI의 기본값에서 가져옴).
-b, --batch-concurrency <n>	파일당 최대 병렬 배치 API 호출 수 (문서 기준; 기본값은 설정 또는 CLI에서 가져옴).
--emphasis-placeholders	번역 전에 마크다운 강조 표시 마커를 플레이스홀더로 마스킹합니다. CJK 및 RTL 로케일의 경우 자동으로 활성화되며, docs[].emphasisPlaceholders을 통해 블록별로 재정의하거나 --no-emphasis-placeholders를 사용하여 비활성화할 수 있습니다.
--debug-failed	전역. 잘못된 스크립트, 구문 분석 또는 품질 등 각 번역 검사 실패에 대해 cacheDir 아래에 상세한 FAILED-TRANSLATION 로그를 작성합니다. 여기에는 모든 모델이 실패한 경우뿐만 아니라 로마자 표기된 zh-Hans/hi와 같은 폴백도 포함됩니다. 제공자 API 오류는 파일 대신 콘솔에 출력됩니다. sync / sync-ui / cleanup에도 적용됩니다.
--check-cache	파일 추적이 건너뛰기를 수행하더라도 네이티브 문자 체계가 강제되는 로케일에 대해 캐시된 세그먼트를 재검증합니다. 예상 문자 체계가 없는 로케일은 여전히 건너뜁니다. 세그먼트 캐시는 계속 적용됩니다.
--force-update	파일 추적이 건너뛸 수 있어도 일치하는 모든 파일을 다시 처리합니다 (추출, 재조합, 출력 쓰기). 세그먼트 캐시는 여전히 적용됩니다 — 변경되지 않은 세그먼트는 LLM에 전송되지 않습니다.
--force	처리된 각 파일에 대한 파일 추적을 지우고 API 번역을 위해 세그먼트 캐시를 읽지 않습니다 (완전한 재번역). 새 결과는 여전히 세그먼트 캐시에 기록됩니다.
--stats	세그먼트 수, 추적된 파일 수, 로케일별 세그먼트 총합을 출력한 후 종료합니다.
--clear-cache [locale]	캐시된 번역(및 파일 추적)을 삭제합니다: 모든 로케일 또는 단일 로케일만 삭제한 후 종료합니다.
--prompt-format <mode>	각 배치의 세그먼트가 모델에 전송되고 파싱되는 방식 (xml, json-array, 또는 json-object). 기본값은 json-array. 추출, 자리표시자, 검증, 캐시, 대체 동작에는 영향을 주지 않음 — 배치 프롬프트 형식 참조.

--force과(와) --force-update을 조합할 수 없습니다 (서로 배타적입니다).

배치 프롬프트 형식

translate-docs는 번역 가능한 세그먼트를 활성 LLM 공급자에게 배치로 보냅니다(batchSize / maxBatchChars로 그룹화됨). --prompt-format 플래그는 해당 배치의 와이어 형식만 변경합니다. PlaceholderHandler 토큰, 마크다운 AST 검사, SQLite 캐시 키 및 배치 구문 분석 실패 시 세그먼트별 대체는 변경되지 않습니다.

모드	사용자 메시지	모델 응답
xml	의사-XML: 각 세그먼트에 하나의 <seg id="N">…</seg> 포함(XML 이스케이프 적용).	각 세그먼트 인덱스에 하나의 <t id="N">…</t> 블록만 포함.
json-array (기본값)	순서대로 세그먼트당 하나의 항목을 가진 문자열의 JSON 배열.	동일한 길이의 JSON 배열 (동일한 순서).
json-object	세그먼트 인덱스로 키가 지정된 JSON 객체 {"0":"…","1":"…",…}.	동일한 키를 가지고 번역된 값을 포함하는 JSON 객체.

일부 모델은 다른 형식보다 특정 형식을 더 안정적으로 따르므로, 모델이 잘못된 배치나 일치하지 않는 세그먼트 ID를 자주 반환하는 경우 다른 모드를 시도해 보십시오. json-array는 모델이 일반적으로 잘 처리하는 흔하고 단순한 형식이기 때문에 기본값입니다.

실행 헤더는 활성 모드를 확인할 수 있도록 Batch prompt format: …도 출력합니다. JSON 레이블 파일(docusaurusCatalogDir) 및 SVG 파일 배치는 해당 단계가 translate-docs(또는 sync의 문서 단계 — sync는 이 플래그를 노출하지 않으며 기본값은 json-array임)의 일부로 실행될 때 동일한 설정을 사용합니다.