문제 해결
번역된 문서에서 섹션 앵커 링크가 작동하지 않음
[label](other.md#section-id)과 같은 링크는 올바른 번역된 파일을 열 수 있지만, 의도한 제목으로 스크롤하지 못하거나 잘못된 섹션으로 이동할 수 있습니다. 해당 로캘에서 #… 조각(fragment)이 더 이상 어떤 제목 id와도 일치하지 않습니다.
일반적인 원인:
- 원본 제목에 명시적인 앵커 ID가 없었으며, 사이트는 보이는 제목 텍스트에서 슬러그를 유도하므로 번역 후 변경됩니다.
- 원본에서 제목을 이름을 변경했지만 이전의
<a id="…"></a>줄이 누락되었거나 여전히 이전 ID를 가지고 있습니다. - 앵커 링크가
write-heading-ids가 생성할 ID 대신 영어 단어에서 추측한#…조각을 사용합니다.
해결 방법
- 소스
.md/.mdx에서ai-i18n-tools write-heading-ids을(를) 실행합니다 (translate-docs와 동일한docs[]/contentPaths). 기본적으로 각 ATX 제목 앞에<a id="slug"></a>을(를) 삽입하거나, 제목 텍스트가 현재 슬러그와 더 이상 일치하지 않을 때 기존 앵커를 갱신합니다. Docusaurus MDX 주석 id의 경우--slug-style mdx-comment을(를) 사용하세요. - 앵커 링크를 해당 id로 지정하세요. 예를 들어
[setup](guide.md#first-run)에서#first-run는 영어 제목만으로 유추한 슬러그가 아니라 대상 제목 바로 위의 앵커 라인과 일치해야 합니다. - 모든 로케일 사본에 업데이트된 앵커 라인이 포함되도록
translate-docs(또는sync --force-update)을(를) 다시 실행하세요.
변경 사항을 미리 보려면 먼저 write-heading-ids에서 --dry-run를 사용하세요. 전체 패턴은 앵커 링크를 참조하세요.
번역된 문서에서 이미지 또는 에셋 링크 404 오류
마크다운 링크 또는 는 영어에서는 작동하지만 번역된 사본에서는 404 오류를 반환합니다. 이는 종종 URL이 여전히 원본 로케일 폴더 또는 영어 전용 정적 경로를 가리키기 때문입니다.
해결 방법
- 에셋 레이아웃이
docsOutput.style와 일치하는지 확인합니다(플랫 vs 문서 시스템). 링크 재작성 및 이미지 및 스크린샷을 참조하십시오. - 로케일 세그먼트를 교체하거나 절대
/img/…경로를 연결하도록docsOutput.postProcessing.regexAdjustments를 추가하거나 조정합니다. 플랫 레이아웃의 경우, 플랫 링크 재작성기가regexAdjustments이전에 실행된다는 점을 기억하십시오. 이미 접두사가 붙은 URL에 대해 패턴을 일치시키십시오. - 재작성된 마크다운이 참조하는 경로에 로케일별 에셋 파일이 있는지 확인하십시오(
translate-docs는 URL을 재작성하지만 래스터 파일을 복사하지는 않습니다).
힌디어, 아랍어, CJK 또는 키릴어 출력이 로마자화됨(라틴 문자)
일부 모델은 의미는 번역하지만 결과를 라틴/로마 문자로 작성합니다(예: 힌디어를 नमस्ते 대신 Namaste로 작성). 단순 hi는 데바나가리 문자를 의미하며, 로마자화된 힌디어가 필요할 때만 hi-Latn를 사용하세요.
해결 방법
- 로케일 코드가 원하는 스크립트와 일치하는지 확인하세요 (
hi대hi-Latn,zh-Hans대zh-Hant,sr대sr-Latn). - 잘못된 스크립트의 캐시 행이 거부되도록 번역을 다시 실행하세요: UI 문자열의 경우
translate-ui --force, 또는translate-docs --check-cache/sync --check-cache(파일 수준 건너뛰기는 예상 스크립트가 있는 로케일에 대해서만 우회됩니다; 유효한 세그먼트 캐시는 여전히 재사용됩니다).--force-update는 모든 로케일을 다시 처리합니다. - 모델이 스크립트 검사를 계속 실패하는 경우, 더 강력한 모델이 먼저 시도되도록 해당 로케일에
localeModels항목을 추가하세요 — 제공자 및 모델을 참조하세요.