Markdown format (.md, .markdown)
The Markdown format reads Markdown documents, extracts prose as translatable blocks, and writes the translations back while preserving the document's structure — headings, lists, emphasis, links, and code. Inline markup (bold, italic, links, inline code) is exposed as inline codes inside each block so the surrounding syntax survives translation.
By default paragraphs, headings, list items, blockquotes, and image alt text are translatable, while code blocks, YAML front matter, raw HTML blocks, and link/image URLs are emitted as non-translatable structure. Each of those categories can be toggled, and embedded HTML can be routed to a subfilter.
How kapi reads it
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
codeFinderRules | array | Regex patterns that match inline codes within translatable text | |
frontMatterKeys | array | Front matter keys to extract when translateFrontMatter is on (empty = every scalar value). Set the prose-bearing keys, e.g. title and description. | |
subfilter | string | Subfilter format to apply to HTML content within Markdown (e.g., 'html') | |
translateBlockQuotes | boolean | true | If true, blockquote content is translatable. |
translateCodeBlocks | boolean | false | If true, fenced and indented code blocks are translatable. If false, emitted as non-translatable data. |
translateFrontMatter | boolean | false | If true, YAML front matter values are translatable. If false, emitted as non-translatable data. |
translateHTMLBlocks | boolean | false | If true, raw HTML blocks are translatable. If false, emitted as non-translatable data. |
translateImageAlt | boolean | true | If true, image alt text is included in translatable content. |
translateURLs | boolean | false | If true, link and image URLs are translatable. |
unescapeBackslashCharacters | boolean | false | Parse backslash-escaped punctuation in source documents |
useCodeFinder | boolean | false | Enable regex-based inline code detection within translatable text |
Configure these parameters interactively and copy the YAML on the Format Reference.
Examples
Translate front matter too
Include YAML front matter values alongside the prose.
translateFrontMatter: true
Handle embedded HTML structurally
Route inline and block HTML through the HTML subfilter.
subfilter: html
Processing notes
Inline markup (emphasis, links, inline code) becomes inline codes within blocks, so it survives translation unchanged.
Structural elements (fences, list markers, heading prefixes) form the non-translatable skeleton.
Limitations
Code blocks, front matter, raw HTML blocks, and URLs are non-translatable by default; enable the corresponding option to extract them.
← Back to the Format Reference