앵커 링크
docsOutput.style = "flat"일 때 출력은 각 로케일에 대해 페이지 간 상대 경로를 다시 작성함(guide.md → guide.de.md). 앵커 링크 — 경로 뒤에 #가 오는 일반적인 마크다운 인라인 형식 — 는 대상 파일 내 섹션으로 이동함:
Read the [installation checklist](setup.md#first-run) before you deploy.여기서 링크 대상은 setup.md이며, #first-run은 앵커입니다. 해당 파일 내 적절한 제목으로 스크롤되어야 합니다.
앵커 링크에 주의해야 하는 이유
rewriteRelativeLinks은 각 로캘의 파일명을 고정합니다(setup.md→setup.de.md).- 많은 렌더러는 보이는 제목 텍스트에서
#슬러그를 유도합니다. 번역 후 제목은 로캘별로 달라지므로 자동 생성된 슬러그는 변경될 수 있지만, 다시 작성된 링크는 여전히#first-run라고 표시될 수 있습니다. 또는 영어#…앵커가 번역된 제목에서 렌더러가 생성한 슬러그와 더 이상 일치하지 않을 수 있습니다. - 결과: 독자는 올바른 파일에는 도달하지만 잘못된 줄에 도달하거나, 브라우저가 일치하는 제목을 찾지 못합니다.
수행할 작업
Docusaurus 사이트 (권장)
Docusaurus 문서(docsOutput.style = "docusaurus")에서는 ai-i18n-tools write-heading-ids의 HTML 앵커 대신 Docusaurus의 네이티브 제목 ID를 사용하는 것을 권장합니다:
- 제목 줄에 명시적 ID를 추가합니다. Docusaurus의 기존
{#…}접미사(CommonMark) 또는 MDX 주석{/* #… */}(.mdx에 권장됨)을 사용하며, 예를 들어## TLS configuration {#tls-configuration}또는## TLS configuration {/* #tls-configuration */}형식을 사용합니다.translate-docs중에는 보이는 제목 텍스트만 모델로 전송됩니다. ID 접미사는 먼저 제거되었다가 번역된 제목 줄의 끝에 다시 고정됩니다(Docusaurus는 제목 중간에 있는{/* #id */}을(를) 무시합니다). - Docusaurus 프로젝트 루트(
package.json에 연결된 경우 보통pnpm run write-heading-ids)에서docusaurus write-heading-ids을(를) 실행하여 ID가 없는 제목에 ID를 추가하거나 새로 고칩니다.{/* #… */}형식에는--syntax mdx-comment을(를) 사용하십시오. 또는 동일한docs[]/contentPaths에서ai-i18n-tools write-heading-ids --slug-style mdx-comment을(를) 실행할 수 있습니다. 이 명령은 기존 번역 파일에서 동일한 영어 ID의 위치를 재지정하며(번역된 제목을 슬러그화하지 않음), 세그먼트 수가 일치할 때 일치하는 캐시된 세그먼트를 업데이트하므로 이후sync --force-update시 수정된 ID가 유지됩니다. 제목 이름을 변경한 후 다시 실행하여 오래된 ID가 현재 제목과 일치하도록 하십시오.
마크다운 앵커 링크를 해당 안정적인 id로 가리키세요(예: [label](other.md#tls-configuration)). 여기서 프래그먼트는 {#…} 또는 {/* #… */} id와 일치해야 하며, 영어 단어만으로 추측한 slug가 아니어야 합니다. 이 패턴을 사용한 커밋된 문서는 examples/docusaurus-docs를 참조하세요.
기타 레이아웃 (플랫, Starlight, VitePress 등)
Docusaurus를 사용하지 않거나, {#…} / {/* #… */} 접미사 대신 HTML 앵커가 필요한 경우:
translate-docs전에 소스.md/.mdx에서ai-i18n-tools write-heading-ids을(를) 실행합니다(평소와 동일한docs[]/contentPaths사용). 이 도구는 각 제목 앞줄에 명시적 HTML 앵커를 삽입하여id값이 모든 번역 사본에서 공유되도록 하고, 동일한 영어 ID를 기존 번역 파일에 복사합니다. 세그먼트 수가 일치하면 일치하는 캐시된 세그먼트도 업데이트되므로, 이후sync --force-update시 수정된 ID가 유지됩니다. 제목 이름을 변경한 후 다시 실행하여 오래된 앵커 ID가 새로 고쳐져 현재 제목과 일치하도록 하십시오.- 마크다운 앵커 링크를 해당 안정적 ID(예:
[label](other.md#section-id))로 지정합니다. 여기서section-id은(는) 도구에서 작성한 앵커와 일치해야 하며, 단순히 영어 단어로 추측한 값이 아니어야 합니다.
예시
Docusaurus {#…} / {/* #… */} 접미사
docs/overview.md:
See [TLS setup](security.md#tls-configuration) for certificate steps.docs/security.md (영어 소스, 클래식):
## TLS configuration {#tls-configuration}
Your CA and cert steps…또는 MDX 권장 주석 형식:
## TLS configuration {/* #tls-configuration */}
Your CA and cert steps…translate-docs 후에도 링크 프래그먼트는 모든 로캘에서 #tls-configuration로 유지되며, 제목 텍스트와 링크 레이블만 변경됩니다:
Siehe [TLS-Einrichtung](security.md#tls-configuration) für die Zertifikatsschritte.HTML 앵커 (write-heading-ids)
docs/overview.md:
See [TLS setup](security.md#tls-configuration) for certificate steps.write-heading-ids 후의 docs/security.md (간소화됨):
<a id="tls-configuration"></a>
---
# TLS configuration
Your CA and cert steps…translate-docs 후, 파일 경로와 #… 앵커는 모든 로캘 파일에서 일치하게 유지됩니다. 예를 들어:
Siehe [TLS-Einrichtung](security.de.md#tls-configuration) für die Zertifikatsschritte.#tls-configuration 앵커는 소스에서 id이 고정되어 있으므로 모든 로캘에서 동일합니다. 제목의 텍스트와 링크 레이블만 번역됩니다.
번역 후에도 링크가 계속 실패하면 문제 해결을 참조하세요.