마크독

주석, 변수, 코드는 그대로 유지하면서 마크독 본문과 선택한 문자열 속성을 번역하세요.

마크독 주석은 문서 본문을 사용자 지정 컴포넌트 및 변수와 연결합니다. markdoc 파일 핸들러는 렌더러에 필요한 주석을 유지하면서 지원되는 본문과 선택한 문자열 값의 태그 속성을 번역합니다.

화면에 표시되는 태그 속성 선택 #

하나의 문서에 화면에 표시되는 메타데이터, 고정된 레이아웃 식별자, 콜아웃을 함께 넣을 수 있습니다.

markdown
---
title: Delivery options
description: Understand the available delivery methods.
layout: article
---

{% callout title="Delivery deadline" type="warning" %}
Confirm your address before checkout.
{% /callout %}

문단과 기본 선택 항목인 프런트매터의 title 및 description는 텍스트입니다. 태그의 title는 속성 규칙으로 선택하면 번역 대상이 됩니다. type="warning" 및 layout: article는 구조적 식별자이므로, 이를 사용하는 쪽에서 번역된 값을 명시적으로 요구하지 않는 한 선택하지 마세요.

규칙을 사용하면 특정 이름의 속성을 모든 태그에서 선택하거나, 이름을 지정한 태그에서만 선택할 수 있습니다. 여러 태그가 같은 속성을 서로 다른 용도로 사용한다면 적용할 태그를 제한하는 방식을 권장합니다. 숫자, 불리언, 변수에서 파생된 값 등 문자열이 아닌 속성은 번역할 일반 텍스트에 해당하지 않습니다.

보호되는 요소 #

펜스로 감싼 코드 블록과 인라인 코드는 번역에서 제외됩니다. 링크의 표시 텍스트는 바뀔 수 있지만 대상 주소는 유지됩니다. 본문에 포함된 인라인 주석과 이미지는 보호되는 구문 요소입니다. 태그 이름과 선택하지 않은 속성도 문서에 그대로 유지됩니다. 핸들러는 번역된 문자열 속성을 마크독의 인용 규칙에 맞게 이스케이프 처리하지만, 렌더러에 필요한 사용자 지정 태그 스키마까지 제공하지는 않습니다.

프런트매터의 title 및 description는 기본적으로 선택됩니다. 프런트매터 선택 항목을 비워 두면 이 값들은 변경되지 않습니다. 맵이나 시퀀스를 선택하면 그 아래에 있는 모든 스칼라 값도 포함됩니다. 인접한 라우팅 필드나 콘텐츠 식별자를 그대로 유지해야 한다면 seo.title처럼 정확한 경로를 선택하세요.

원문과 번역문의 대응 관계 유지 #

재구성 과정에서는 현재 원문의 텍스트 구간을 교체하며, 서로 대응하는 이전 원문과 번역문의 표현을 재사용할 수 있습니다. 두 문서의 보호된 인라인 구조가 안전하게 대응하지 않으면 재사용에 실패할 수 있습니다. 특히 태그를 옮기거나 링크를 변경한 뒤에는 승인된 번역과 짝을 이루는 원문 버전을 보관하세요.

마크독 주석이 포함된 .md 문서라고 해서 이 핸들러가 선택되는 것은 아닙니다. CLI는 .md의 형식을 마크다운으로 추론합니다. 문서 언어에 마크독 방식의 처리가 필요하다면 형식을 명시적으로 선택하세요.

마크독 번역 설정 #

CLI는 .mdoc에서 markdoc 형식을 추론하며, 키 범위 지정은 지원하지 않습니다. 프런트매터, 태그 속성 선택, 대상 레이아웃을 설정하려면 CLI 설정을, 저장소 워크플로를 설정하려면 GitHub를 참고하세요.

사이트 스키마로 검증 #

파일 핸들러는 프레임워크 라우트, 콘텐츠 로딩, 애플리케이션의 마크독 변환을 설정하지 않습니다. 번역문을 가져온 뒤에는 원문과 동일한 스키마로 파싱하고 렌더링하세요. 번역된 문단뿐 아니라 화면에 표시되는 속성, 링크 대상 주소, 변수, 선택한 프런트매터도 함께 확인하세요.