CLI 옵션

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

캐시 동작 및 translate-docs 플래그

CLI는 SQLite에 파일 추적(파일당 소스 해시 × 로케일) 및 세그먼트 행(번역 가능한 청크당 해시 × 로케일)을 유지합니다. 일반적인 실행은 추적된 해시가 현재 소스와 일치하고, 출력 파일이 이미 존재하며, 그리고 출력의 수정 시간이 소스의 수정 시간보다 최신인 경우 파일을 완전히 건너뜁니다. 그렇지 않으면 파일을 처리하고 세그먼트 캐시를 사용하여 변경되지 않은 텍스트가 API를 호출하지 않도록 합니다.

플래그	효과
(기본값)	추적 중인 파일과 디스크에 있는 출력이 동일할 경우 건너뛰고, 나머지에는 세그먼트 캐시를 사용합니다.
-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	검증에 실패할 경우 FAILED-TRANSLATION 로그를 cacheDir 아래에 자세히 기록합니다.
--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임)의 일부로 실행될 때 동일한 설정을 사용합니다.