Markdown
Translate document prose and selected frontmatter while retaining code, links, and the structure needed to reuse accepted wording.
A Markdown document combines an explanation with structure readers use to follow it. The md file handler translates prose in headings, paragraphs, table cells, and supported directive labels while protecting code and link destinations. The result remains Markdown for your existing renderer.
Text and protected structure #
For example, the link label can change while its destination and the function name stay fixed:
---
title: Delivery options
description: Choose how your order arrives.
slug: delivery
---
## Choose delivery
Read the [delivery policy](/policies/delivery) before calling `confirmOrder()`.The heading, paragraph wording, and link label are text. The link destination and inline code are protected structure. In the normal document profile, fenced code and raw HTML are outside prose extraction. Use HTML when the source is an HTML document, or Markdoc when custom Markdoc tags are part of the document language.
Frontmatter selection #
By default, the file handler selects title and description. Other fields stay unchanged unless explicitly selected. An empty translateFrontmatterFields list opts out of frontmatter translation. Choosing fields is a content decision: a readable headline can be translated, while a slug, component identifier, or routing key may need to remain fixed.
Supported field paths can address nested values, including sequence members. Selecting a map or sequence includes its scalar descendants. Choose a precise path such as seo.title when neighboring routing fields must stay fixed. Use the selected interface's frontmatter options to select the text.
Reuse requires aligned documents #
The handler matches text units against the previous source and corresponding target, then inserts changed translations into the current source structure. Existing wording can be reused only when its correspondence is clear. If the previous source and target contain different protected inline structures, reuse can fail with a structure mismatch.
Retain the source revision associated with accepted target wording. If the target has been reorganized independently, reconcile its structure with that source before requesting an incremental update. Build the result with your site's Markdown processor to check any dialect-specific constructs.
Configure and render the document #
The CLI infers md from .md. Configure file selection, frontmatter fields, and output paths in CLI configuration, or use GitHub for managed repository translation. CLI key scope is unavailable for Markdown.
Render the output with your site's Markdown processor. Check translated metadata, links, heading fragments, and code examples together. Preserving /policies/delivery does not create that page in another language. The static-content guide connects output paths to the site's loader and locale routes.