번역 실패 (문서 번역)
실패 탭은 문서 번역 전용입니다. 로케일에 대해 세그먼트를 성공적으로 번역할 수 없을 때 SQLite에 기록된 실패 기록을 읽습니다. 예를 들어 빈 또는 잘못된 모델 출력, 번역 후 유효성 검사 오류(AST mismatch, 플레이스홀더 누수 및 유사한 품질 확인) 또는 진행을 차단한 치명적인 조건입니다.
이것은 다음 질문에 대한 답을 도와줍니다: 어느 소스 세그먼트가 깨졌는지, 어느 로케일과 모델에서, 그리고 어떤 오류 텍스트가 기록되었는지?
언제 사용하는가
translate-docs또는sync이 오류, 부분 로케일 또는混乱한 로그와 함께 완료된 후 — 터미널 출력만 스크롤하는 대신 실패를 정렬하고 필터링합니다.- 재작업을 우선순위로 할 때: # 실패으로 정렬하여 재시도에서 반복적으로 실패한 세그먼트가 먼저 나타나도록 합니다. 이러한 세그먼트는 소스 마크다운에서 간소화 또는 재형식화할 강력한 후보입니다.
- 정확한 세그먼트 — 파일 경로, 줄 힌트, 소스 해시 및 전체 소스 텍스트 —를 편집하여 리포지토리에서 올바른 단락을 편집할 때 필요합니다.
소스 편집이 중요한 이유
.Dense 인라인 마크업 (굵은 기호가 `code`와 섞여 있거나, 강조가 중첩되거나, 여러 스팬이 있는 긴 문장)으로 인해 모델이 구조적 검사를 통과하는 번역을 반환하기가 더 어려워집니다. 여러 번 기록된 실패가 있는 세그먼트는 일반적으로 번역을 다시 실행하는 것보다 소스를 재작성하거나 분할하거나(또는 예제를 코드 블록으로 이동하는 것보다) 더 많은 개선이 있습니다. 이는 복잡한 마크다운과 실패한 품질 검사와 일치합니다.
사용 방법
- 대시보드에서 실패를 엽니다.
- 요약 스트립을 읽습니다 — 모든 실패를 가진 세그먼트, 1, 2, 3+ 실패 기록에 대한 카운트가 포함됩니다.
- 부분 파일 이름, 로케일, 모델, 품질 오류(값은 캐시에서 가져옴), 치명적인 오류, 소스 해시, 소스 텍스트 또는 오류 메시지의 하위 문자열로 필터링 — 그런 다음 적용을 클릭합니다.
- 정렬: # 실패(기본값) 또는 정렬: 파일 경로 + 줄 번호를 선택합니다.
- 표의 상단 또는 하단에 페이지네이션을 사용하세요. 행을 클릭하여 전체 소스 텍스트를 확장합니다. 모델 열에는 실패 모델과 사용 가능한 경우 이후 성공한 캐시 항목의 모델이 표시됩니다.
- 🔗 링크 제어는 터미널에서
ai-i18n-tools dashboard이 실행 중인 파일/줄 힌트를 기록합니다. - 프로젝트의 소스 파일을 수정한 다음
translate-docs또는sync를 다시 실행하세요. 성공적인 실행 후 목록이 최신이 아닌 것으로 보인다면ai-i18n-tools sync --force-update을 실행하고 대시보드를 다시 로드하세요.
UI와 함께 파일 기반 디버깅을 위해 translate-docs --debug-failed를 사용하여 FAILED-TRANSLATION 세부 정보를 cacheDir에서 재시도 중에 작성합니다. 캐시 동작 및 translate-docs 플래그를 참조하십시오.
실패 vs 마크다운 문제
| 실패 | 마크다운 문제 | |
|---|---|---|
| 기록된 시점 | 번역 중(로케일당) | 번역 전(소스 스캔) |
| 일반적인 원인 | 모델 출력이 나쁨, 유효성 검사 오류 | 일치하지 않는 강조, 닫히지 않은 코드 범위, 링크 외부의 볼드 |
| 수정 | 소스를 수정하고 다시 번역 | 소스 마크다운을 수정한 다음 다시 번역 |
마크다운 문제를 참조하여 사전 번역 정적 확인을 수행하십시오.