CLI — 문서
translate-docs
개요: ai-i18n-tools translate-docs [options]
각 docs 블록에 대해 마크다운, MDX, .astro, 선택적 Docusaurus 카탈로그 JSON(docusaurusCatalogDir), 선택적 Nextra _meta.ts/사전 .ts, 선택적 VitePress 테마 카탈로그를 번역합니다.
주요 옵션: -l, -j, -b, --prompt-format, --force, --force-update, --check-cache, --recheck-glossary-warnings, -p / -f, --dry-run
-j: 최대 병렬 로케일; -b: 파일당 최대 병렬 배치 API 호출. --prompt-format: 배치 와이어 형식(xml | json-array | json-object).
참고 항목: 캐시 동작 및 translate-docs 플래그, 배치 프롬프트 형식
write-heading-ids
개요: ai-i18n-tools write-heading-ids [options]
하나 이상의 docs[] 블록이 필요합니다. 각 블록의 contentPaths 아래에 .md / .mdx를 수집합니다(.translate-ignore를 준수합니다). 기본적으로 각 플랫 ATX # 헤딩 바로 앞에 HTML 앵커 라인 <a id="slug"></a>를 삽입합니다(펜스드 코드 블록 내부의 헤딩은 건너뜁니다). 모든 형태의 기존 헤딩 ID(HTML 앵커 라인, 기존 {#id} 접미사, MDX {/* #id */} 주석)는 선택된 스타일로 대체됩니다. 슬러그는 항상 현재 헤딩 텍스트에서 파생됩니다. 여러 HTML 앵커가 하나의 헤딩 위에 쌓여 있을 때, 현재 헤딩 텍스트에 대한 앵커만 유지되며, 제거된 ID를 가리키던 저장소 내 마크다운 링크는 남아 있는 ID로 업데이트됩니다. 헤딩 바로 위에 있지 않은 <a id>는 그대로 유지됩니다. --slug-style mdx-comment를 사용하면 대신 헤딩 라인에 Docusaurus MDX 주석 접미사를 작성하고(동일한 GitHub 스타일 슬러그 알고리즘), 선행 HTML 앵커 블록이 있는 경우 삭제합니다. --remove는 해당 헤딩 ID 형식을 모두 제거하고 그 자리에 아무것도 작성하지 않습니다.
소스 파일을 업데이트한 후, 명령어는 각 로캘의 기존 번역된 마크다운도 순회합니다(translate-docs과 동일한 docsOutput 경로 매핑). 이 명령어는 소스 로캘 제목 ID를 문서 순서에 따라 일치하는 ATX 제목에 복사하고(번역된 제목은 절대 슬러그화하지 않음), 제목 중간의 {#id} / {/* #id */}(또는 불필요한 HTML <a id>)을 Docusaurus / 선택한 스타일이 예상하는 형식으로 다시 이동시킵니다. 소스 언어는 sourceLocale이며 모든 언어가 될 수 있습니다. 누락된 번역 파일은 건너뜁니다. --remove는 잘못 배치된 줄 중간 토큰을 포함하여 해당 번역 파일에서도 제목 ID를 제거합니다.
번역된 파일의 제목 ID 위치가 변경되거나 복구될 때, 소스 콘텐츠와 이전 및 새 번역 콘텐츠의 세그먼트 수가 동일하면 일치하는 캐시된 번역 세그먼트(소스 세그먼트 해시를 키로 사용)도 업데이트됩니다. 개수가 일치하지 않으면 해당 파일과 로캘을 건너뜁니다. 이후 sync --force-update는 업데이트된 캐시 행에서 파일을 다시 조합합니다.
주요 옵션: -p / --path, -f / --file, --slug-style, --remove, --dry-run
--slug-style: github(기본값; doctoc / anchor-markdown-header), bitbucket, gitlab, pymdown, azure-devops, mdx-comment(Docusaurus {/* #… */} 접미사). pymdown 사용 시, 선택적 --pymdown-case, --pymdown-normalize, --pymdown-percent-encode / --no-pymdown-percent-encode. --remove는 --pymdown-*와 함께 사용할 수 없습니다.
참고 항목: 앵커 링크
check-markdown
개요: ai-i18n-tools check-markdown [options]
각 docs[] 블록의 contentPaths 아래에 있는 마크다운/MDX를 스캔합니다(translate-docs와 동일한 검색, .translate-ignore 적용): 구분자 쌍, 닫히지 않은 인라인 코드, 그리고 **/__가 [text](url) 링크를 감쌀 때 STRONG_OUTSIDE_LINK.
relativePath:line: [ISSUE_CODE] message 줄을 stderr로 출력합니다. 문제가 발견되면 코드 1로 종료합니다. --json: stdout으로 JSON 보고서를 출력합니다. --no-cache가 아닌 경우 cacheDir에 markdown_source_issues를 작성합니다. -v는 stderr 줄에 소스 해시를 추가합니다.
주요 옵션: -p / --path, -f / --file, --json, --no-cache
참고 항목: 마크다운 문제