How can you translate Markdown documentation without breaking code fences, relative links, inline commands or headings? A reliable Markdown localization workflow distinguishes reader-facing prose from CommonMark syntax, link destinations, identifiers and executable examples. This guide explains how to translate Markdown files safely for software documentation, README pages, help centres and multilingual technical guides while preserving what readers can click, copy and run.
The visible problem is that a Markdown document often looks like plain text. A translator can improve every sentence but accidentally translate a shell command, change a relative path, remove the backticks around an option, misalign a reference link or alter a heading anchor used by another page. The file may still open in a text editor and yet render incorrectly, lead to a 404 page or present untested code as if it were valid in the target environment.
- Identify which Markdown dialect and renderer the project actually uses.
- Translate explanatory prose and user-facing link text while protecting code, paths and destinations.
- Preserve fenced code block delimiters, info strings and indentation rules.
- Check reference-style links, headings, anchors and image destinations separately.
- Render both language versions, inspect diffs and click internal paths.
- Ask maintainers to approve intentional code or link changes outside translation.
The answer is to separate content translation from parser behavior, run a repeatable syntax-aware workflow and test both rendered output and actual reader tasks. This article focuses specifically on Markdown documentation and its syntax boundaries. It does not replace the broader guides for software-string plural rules, source-code localization, document layout, general glossary decisions or website SEO.
Why translating a README as plain text is unsafe
The difficulty in syntax-safe Markdown documentation localization is that one file combines human prose with formatting commands and real resource addresses. Human words and special syntax can sit a few characters apart. Editors need to know whether they are changing a sentence, a literal token or an address. A translation that wins an editorial review but causes a documentation link to fail is not correct in the reader’s real working environment.
The consequences can be operational: readers may follow a broken link, paste an invalid command or misunderstand a procedure because the document still looks superficially correct. A document may be used by a student learning a command for the first time, by a support technician responding to a production incident, or by a multilingual contributor trying to improve a project. The translated page needs to support the same safe task; it must not silently turn an instruction into a different action.
Start with a four-way classification: reader prose, Markdown parser syntax, code or identifier bytes, and resource pointers. Translate the first with attention to purpose; protect the others unless the project has explicitly designed a coordinated localization or migration. A correct target document is both semantically faithful and syntactically stable. Its quality can be tested by parsing, rendering, navigating and following the documented procedure.
Core principles: what each Markdown feature means in translation
1. Markdown is a format, not plain prose
First principle. CommonMark specifies how punctuation and whitespace produce blocks, headings, lists, code spans, links and other structures. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. A translator may remove a marker to improve typography and change the parsed document. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Identify the renderer and translation-eligible segments before rewriting sentences. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Render the source and target to inspect structure as well as wording. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
2. Renderer and dialect choice
First principle. CommonMark provides a core specification, while platforms may support extensions such as tables or task lists. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Assuming every GitHub-style feature works everywhere can cause a target document to render as raw punctuation. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Declare whether the target uses CommonMark, GitHub Flavored Markdown or another documented dialect. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Run the same rendering pipeline used on the destination site. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
3. ATX headings
First principle. Leading hash markers create headings and the wording after them can be translated. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Removing a space or changing heading markers can turn a heading into an ordinary line or malformed text. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Preserve the level, translate the heading text and check generated anchors separately. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Compare the heading outline and links targeting it. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
4. Setext headings
First principle. Underline-like runs of equals or hyphen characters can create headings. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. A translator may mistake the hyphen line for punctuation and delete it. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Maintain the recognized structure when translating the heading, or convert through an authorised editorial change. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Render both versions to confirm the same heading hierarchy. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
5. Fenced code blocks
First principle. Backtick or tilde fences delimit code blocks, often with a language info string. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Changing fence lengths or translating an info string such as python can make code disappear or syntax highlighting fail. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Preserve delimiters and lexer tags while translating permitted comments only when instructed. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Verify a renderer shows the exact intended code block with correct syntax highlighting. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
6. Code spans
First principle. Single or multiple backticks distinguish literal code, filenames, API keys and commands from surrounding prose. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Translating a token in code spans can make an example unusable even though the sentence is grammatically good. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Translate the prose around code while retaining exact literal tokens unless a tested alternative exists. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Copy the command and compare its bytes with the approved source example. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
7. Indented code
First principle. Indentation may designate code blocks or list nesting depending on context. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Aggressive reflow can promote code to paragraphs or break nesting under bullets. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Keep structural indentation and use the project’s formatter with care. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Render nested lists and code blocks and inspect boundaries. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
8. Inline links
First principle. In Markdown links the bracketed text is the reader’s label and the parenthesized destination points to a resource. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. A translated link destination may no longer exist or may contain broken percent encoding. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Localize link text and preserve URLs or replace them only with a verified locale-specific destination. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Click the rendered link and check that the destination matches its label. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
9. Reference links
First principle. A link can point to a separately defined reference label rather than carrying its destination inline. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. A translator may change only the occurrence of the reference identifier and forget the definition. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Keep reference identifiers stable or update every use and definition together as a controlled change. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Use a link checker and inspect unresolved reference forms in rendered output. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
10. Images and alt text
First principle. Image syntax distinguishes descriptive alt text from its image resource destination. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Replacing the image path with translated words breaks the picture, while translating alt text blindly may distort the image’s purpose. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Translate a meaningful alt-text description based on the actual image and preserve verified resource paths. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Inspect image loading, alt text and surrounding explanatory caption. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
11. Relative file paths
First principle. A path such as ../guides/setup.md resolves relative to the current file location. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Moving a translated file into a new locale folder can make an unchanged source-relative path incorrect. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Resolve paths against the target directory layout and adjust only through explicit link mapping. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Test each relative path from the deployed target document. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
12. Headings and auto-generated anchors
First principle. Some renderers derive fragment identifiers from heading text using platform-specific rules. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Translating a heading can change its automatically generated anchor, breaking links elsewhere. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Inventory inbound fragment links and handle heading-anchor changes according to renderer behavior. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Open links arriving from other documents, not just links leaving the translated file. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
13. Escapes and literal punctuation
First principle. A backslash can escape special punctuation; entities and inline HTML may have their own parsing rules. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Removing escapes to improve readability can unexpectedly trigger emphasis, links or tags. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Preserve literal intent while using syntax that renders correctly in the target dialect. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Compare the rendered characters and raw source in representative tricky sentences. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
14. Lists and steps
First principle. Markdown list markers and indentation convey sequence and nested instructions. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Reordering numbered steps for linguistic fluency can reverse a real operational workflow. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Translate each instruction while keeping procedural order and nesting intact. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Have a reader follow the rendered procedure from start to finish. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
15. Line wrapping and hard breaks
First principle. A newline, trailing spaces or a backslash can affect line breaks depending on syntax and renderer. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Automated cleanup can merge two required instruction lines or create an unwanted break. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Use formatter-aware reflow and preserve explicit line-break intent. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Inspect the rendered spacing rather than inferring it from the source editor. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
16. Raw HTML inside Markdown
First principle. Some Markdown documents embed HTML tags for details, anchors or other presentation features. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. Treating tags as English sentences can break markup or introduce unsafe unreviewed HTML. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Protect attributes and element structure; localize only approved text nodes and applicable user-facing attribute values. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Run HTML-aware validation and review the rendered result. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
17. Tables and extensions
First principle. Table syntax may be supplied by a platform extension rather than core CommonMark. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. A translated cell containing a pipe character can create an extra column or misaligned data. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Verify the renderer supports tables and escape structural separators appropriately. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Check columns, row labels and screen-reader usability in the actual output. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
18. Executable examples
First principle. README code blocks may contain shell commands, environment variables or API endpoint examples. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. A translator may edit a command to sound natural and inadvertently change its behavior. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Treat runnable commands as locked code and document separate platform-localization adjustments with tests. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Have a qualified maintainer execute or statically validate representative examples safely. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
19. Version and build instructions
First principle. Documentation often applies only to a particular software version or deployment. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. A localized file may omit a caution and make old commands sound current. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Keep version qualifiers, warnings and prerequisites precisely aligned with the source and the product release. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Cross-check versions and prerequisites with the maintained documentation branch. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
20. Change tracking and merge conflicts
First principle. Translated Markdown is often stored in source control and rebased as upstream docs evolve. Classify the string before writing any target-language equivalent. A full sentence may sit beside a token that appears English but functions as a command, key or reference. The translator’s job is to improve what the reader reads without altering what the parser or program requires.
Recognise a likely failure. A stale target can retain a deprecated instruction while new English changes are partially copied. Such mistakes can survive a normal proofread because the raw file is legible. The result can still be unhelpful, broken or misleading once parsed into HTML, moved to a locale folder or copied into a terminal.
Repeatable correction. Track source revision, target revision and any strings requiring retranslation after a merge. Keep an extraction sheet with source span, target span, protected characters, destination and test. Where a change touches code or package structure, obtain maintainers’ approval and document it as an engineering change rather than hiding it in a translation revision.
Proof of quality. Inspect a source-target diff and confirm every changed instruction was accounted for. Use a rendered comparison, an automated check if available and a human task test. A reviewer should be able to explain exactly how the reader finds the same content or completes the same safe action in the target version.
Twelve-stage Markdown localization method
Stage 1: Find the true renderer
Confirm whether the project uses CommonMark, GitHub Flavored Markdown, a static-site generator or a custom documentation framework. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 2: Protect the baseline
Save the source revision, the source build output and the directory layout before translation begins. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 3: Map special syntax
Inventory headings, links, images, code spans, fenced blocks, HTML elements, tables and custom extensions. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 4: Extract reader language
Separate captions, prose, warning text and reader-facing link labels from code, paths, reference IDs and other technical syntax. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 5: Lock high-risk tokens
Mark command-line options, environment variables, version strings, placeholder identifiers, URLs and resource paths as immutable unless sanctioned. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 6: Translate with task context
Make instructions clear and concise in the target language without changing their step order, conditions or warnings. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 7: Review link paths and anchors
Resolve relative destinations from the target document location and identify headings whose generated fragments change after translation. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 8: Reinsert with syntax protection
Preserve Markdown markers, compatible escapes, fences, list indentation and reference-definition relationships. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 9: Build with target tooling
Use the actual target renderer and inspect headings, images, tables, code formatting and callouts. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 10: Validate navigation
Run link checks, verify referenced files and test paths that lead to other help pages or sections. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 11: Review procedural safety
Have a qualified reviewer check command and configuration examples; execute only in a safe test environment when appropriate. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Stage 12: Record source-to-target evidence
Keep the version baseline, nonlinguistic exceptions, QA output and approval for any intentional technical change. Record a concrete artifact for this stage: a file map, protected-string list, rendered screenshot, link report, tested command or approval note. When an error appears, classify whether the problem lies in language, parsing, resource resolution or source instructions. That prevents expensive cycles of retranslating prose when the real fault is a malformed link or incompatible Markdown extension.
Worked Markdown cases: source, trap, decision and verification
Worked case 1: Inline guide link
Starting material: [Install the tool](../install.md). Misleading shortcut: Do not translate ../install.md as if it were a sentence. Safer treatment: Translate ‘Install the tool’ and resolve the existing path correctly. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Link text and destination occupy different syntax roles. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 2: A command span
Starting material: Run `npm install` to get started. Misleading shortcut: Do not translate npm install into a local-language phrase. Safer treatment: Translate the surrounding prose while preserving the tested command. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Readers may copy the literal code directly. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 3: A fenced Python block
Starting material: A code block opens with three backticks followed by python. Misleading shortcut: Do not translate the python info string or drop the closing fence. Safer treatment: Keep the code fence and language token intact. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: A missing fence can swallow the rest of the document. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 4: A shell option
Starting material: Use `–dry-run` before deleting files. Misleading shortcut: Do not convert the option name to a translated flag. Safer treatment: Explain what the option does in prose while retaining its literal spelling. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: The command parser expects exact option bytes. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 5: Reference-style link
Starting material: [Read the guide][setup] plus [setup]: docs/setup.md. Misleading shortcut: Do not translate [setup] only in one place. Safer treatment: Preserve or consistently remap the reference identifier and its definition. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Both sides must resolve together. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 6: Heading anchor
Starting material: A link targets #getting-started on a README page. Misleading shortcut: Do not assume a translated heading keeps the same autogenerated slug. Safer treatment: Check the renderer’s target anchor behavior and repair links through an approved map. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Heading translation can change externally referenced fragments. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 7: Image alt and path
Starting material: . Misleading shortcut: Do not translate images/architecture.svg into a descriptive phrase. Safer treatment: Translate the alt text based on the diagram while preserving a valid target asset path. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: The alt field is human meaning; the image destination is a resource. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 8: Nested ordered list
Starting material: A second-level task belongs below Step 3. Misleading shortcut: Do not flatten indentation to make the file shorter. Safer treatment: Keep semantic nesting while translating the instruction. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: A reader should understand which task belongs to which step. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 9: Code-fence containing backticks
Starting material: A sample shows Markdown inside a longer fenced code block. Misleading shortcut: Do not close the outer fence at the first inner backtick run. Safer treatment: Use a valid outer delimiter length and preserve the intended literal example. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Fence matching follows parser rules, not visual intuition. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 10: Localised README directory
Starting material: README.fr.md sits beside README.md. Misleading shortcut: Do not assume every ../ relative path still means the same destination. Safer treatment: Resolve each link from the target file’s actual directory. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Relative resolution changes with file location. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 11: Query string in a URL
Starting material: [Search](https://example.org/find?q=language%20tools). Misleading shortcut: Do not translate the encoded q value without checking the receiving service. Safer treatment: Preserve the verified URL and translate its label. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Queries are actionable parameters. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 12: Pipe in a table
Starting material: A row cell includes the text ‘A | B’. Misleading shortcut: Do not introduce a raw separator that splits one cell into two. Safer treatment: Escape or encode pipe content according to the target renderer. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: The delimiter can be syntax rather than meaning. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 13: Literal asterisk
Starting material: The document shows an asterisk as a symbol in an instruction. Misleading shortcut: Do not let the asterisk begin unintended emphasis. Safer treatment: Use approved escaping when a literal symbol is required. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Readable punctuation can acquire parser meaning. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 14: Hard line break
Starting material: Two address lines are deliberately separated. Misleading shortcut: Do not merge them into one rendered line by removing the break mechanism. Safer treatment: Preserve the renderer-specific break syntax. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Source newlines do not always equal visual newlines. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 15: Shell environment variable
Starting material: Set `APP_HOME` in the environment. Misleading shortcut: Do not translate APP_HOME as an ordinary noun. Safer treatment: Keep exact variable spelling and translate the explanation. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Programs reference variable names literally. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 16: HTML anchor
Starting material: An embedded HTML anchor has id=’configuration’. Misleading shortcut: Do not translate the ID without auditing incoming links. Safer treatment: Translate nearby text, protect anchor identity. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: An ID creates a link destination. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 17: A link to another locale
Starting material: The site has an authorised /fr/ guide. Misleading shortcut: Do not invent /fr/ just because the content is French. Safer treatment: Use only verified locale-specific targets, otherwise retain the available supported link. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Link localization needs destination confirmation. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 18: A version warning
Starting material: The README says the command applies to versions 2.4 to 2.6. Misleading shortcut: Do not broaden the statement to all versions. Safer treatment: Keep scope, qualifiers and prerequisite language accurate. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: An outdated command can have operational consequences. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 19: A checklist item
Starting material: – [ ] Verify backups before migration. Misleading shortcut: Do not remove square brackets or change checklist state unintentionally. Safer treatment: Translate the text while keeping task syntax recognized by the renderer. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Checklist syntax may be platform-specific. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 20: A code comment
Starting material: An example contains a comment explaining a parameter. Misleading shortcut: Do not edit runnable code and comments as one unrestricted language field. Safer treatment: Translate comments only if the project permits, then review with a maintainer. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Comments may be localizable while code tokens are protected. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 21: A relative image
Starting material:  in a moved locale folder. Misleading shortcut: Do not assume the source path survives unchanged. Safer treatment: Check target directory path and asset resolution before publication. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: The path may need a controlled remap. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 22: An admonition block
Starting material: A project uses a custom :::warning syntax. Misleading shortcut: Do not assume the extension is CommonMark. Safer treatment: Check the plugin or renderer documentation and preserve the extension delimiter. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Extensions have parser-specific rules. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 23: A footnote extension
Starting material: Text uses [^note1] and its definition. Misleading shortcut: Do not translate only the identifier in the callout. Safer treatment: Treat extension labels as linked references. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: An unsupported or broken footnote can print as raw punctuation. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Worked case 24: A shell prompt in code
Starting material: A documentation example shows `$ tool –help`. Misleading shortcut: Do not instruct readers to paste a decorative prompt if the actual command excludes it. Safer treatment: Explain copyable content and preserve the source example’s intended semantics. The key is to make a deliberate decision about each substring rather than trusting a whole-file translation pass to recognise programming and markup conventions.
Reasoning: Text display and executable command are not always identical. A complete quality check compares the raw source, the target Markdown and its rendered output. If this item points to another file, follow it from the target file’s deployed location. If it instructs the reader to run a command, protect its precise syntax and ask a maintainer to confirm the intended outcome. Fluent prose alone cannot prove that the documented task remains possible.
Failure diagnosis and rapid repair
Failure mode 1: Markdown is a format, not plain prose
The reported symptom often emerges from this pattern: a translator may remove a marker to improve typography and change the parsed document. Resist a superficial rewrite. Instead, identify the renderer and translation-eligible segments before rewriting sentences. The acceptance criterion is specific: render the source and target to inspect structure as well as wording. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 2: Inline links
The reported symptom often emerges from this pattern: a translated link destination may no longer exist or may contain broken percent encoding. Resist a superficial rewrite. Instead, localize link text and preserve URLs or replace them only with a verified locale-specific destination. The acceptance criterion is specific: click the rendered link and check that the destination matches its label. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 3: Line wrapping and hard breaks
The reported symptom often emerges from this pattern: automated cleanup can merge two required instruction lines or create an unwanted break. Resist a superficial rewrite. Instead, use formatter-aware reflow and preserve explicit line-break intent. The acceptance criterion is specific: inspect the rendered spacing rather than inferring it from the source editor. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 4: Renderer and dialect choice
The reported symptom often emerges from this pattern: assuming every GitHub-style feature works everywhere can cause a target document to render as raw punctuation. Resist a superficial rewrite. Instead, declare whether the target uses CommonMark, GitHub Flavored Markdown or another documented dialect. The acceptance criterion is specific: run the same rendering pipeline used on the destination site. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 5: Reference links
The reported symptom often emerges from this pattern: a translator may change only the occurrence of the reference identifier and forget the definition. Resist a superficial rewrite. Instead, keep reference identifiers stable or update every use and definition together as a controlled change. The acceptance criterion is specific: use a link checker and inspect unresolved reference forms in rendered output. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 6: Raw HTML inside Markdown
The reported symptom often emerges from this pattern: treating tags as English sentences can break markup or introduce unsafe unreviewed HTML. Resist a superficial rewrite. Instead, protect attributes and element structure; localize only approved text nodes and applicable user-facing attribute values. The acceptance criterion is specific: run HTML-aware validation and review the rendered result. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 7: ATX headings
The reported symptom often emerges from this pattern: removing a space or changing heading markers can turn a heading into an ordinary line or malformed text. Resist a superficial rewrite. Instead, preserve the level, translate the heading text and check generated anchors separately. The acceptance criterion is specific: compare the heading outline and links targeting it. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 8: Images and alt text
The reported symptom often emerges from this pattern: replacing the image path with translated words breaks the picture, while translating alt text blindly may distort the image’s purpose. Resist a superficial rewrite. Instead, translate a meaningful alt-text description based on the actual image and preserve verified resource paths. The acceptance criterion is specific: inspect image loading, alt text and surrounding explanatory caption. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 9: Tables and extensions
The reported symptom often emerges from this pattern: a translated cell containing a pipe character can create an extra column or misaligned data. Resist a superficial rewrite. Instead, verify the renderer supports tables and escape structural separators appropriately. The acceptance criterion is specific: check columns, row labels and screen-reader usability in the actual output. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 10: Setext headings
The reported symptom often emerges from this pattern: a translator may mistake the hyphen line for punctuation and delete it. Resist a superficial rewrite. Instead, maintain the recognized structure when translating the heading, or convert through an authorised editorial change. The acceptance criterion is specific: render both versions to confirm the same heading hierarchy. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 11: Relative file paths
The reported symptom often emerges from this pattern: moving a translated file into a new locale folder can make an unchanged source-relative path incorrect. Resist a superficial rewrite. Instead, resolve paths against the target directory layout and adjust only through explicit link mapping. The acceptance criterion is specific: test each relative path from the deployed target document. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Failure mode 12: Executable examples
The reported symptom often emerges from this pattern: a translator may edit a command to sound natural and inadvertently change its behavior. Resist a superficial rewrite. Instead, treat runnable commands as locked code and document separate platform-localization adjustments with tests. The acceptance criterion is specific: have a qualified maintainer execute or statically validate representative examples safely. When the same issue repeats across files, make a protected-string rule or lint check for that syntax class and retest the complete documentation build.
Practice and transfer: ten exercises with model answers
Practice 1: A fenced Python block
Task: Review A code block opens with three backticks followed by python. Someone proposes: do not translate the python info string or drop the closing fence. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Keep the code fence and language token intact. This matters because a missing fence can swallow the rest of the document. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 2: Reference-style link
Task: Review [Read the guide][setup] plus [setup]: docs/setup.md. Someone proposes: do not translate [setup] only in one place. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Preserve or consistently remap the reference identifier and its definition. This matters because both sides must resolve together. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 3: Image alt and path
Task: Review . Someone proposes: do not translate images/architecture.svg into a descriptive phrase. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Translate the alt text based on the diagram while preserving a valid target asset path. This matters because the alt field is human meaning; the image destination is a resource. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 4: Code-fence containing backticks
Task: Review A sample shows Markdown inside a longer fenced code block. Someone proposes: do not close the outer fence at the first inner backtick run. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Use a valid outer delimiter length and preserve the intended literal example. This matters because fence matching follows parser rules, not visual intuition. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 5: Query string in a URL
Task: Review [Search](https://example.org/find?q=language%20tools). Someone proposes: do not translate the encoded q value without checking the receiving service. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Preserve the verified URL and translate its label. This matters because queries are actionable parameters. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 6: Literal asterisk
Task: Review The document shows an asterisk as a symbol in an instruction. Someone proposes: do not let the asterisk begin unintended emphasis. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Use approved escaping when a literal symbol is required. This matters because readable punctuation can acquire parser meaning. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 7: Shell environment variable
Task: Review Set `APP_HOME` in the environment. Someone proposes: do not translate APP_HOME as an ordinary noun. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Keep exact variable spelling and translate the explanation. This matters because programs reference variable names literally. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 8: A link to another locale
Task: Review The site has an authorised /fr/ guide. Someone proposes: do not invent /fr/ just because the content is French. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Use only verified locale-specific targets, otherwise retain the available supported link. This matters because link localization needs destination confirmation. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 9: A checklist item
Task: Review – [ ] Verify backups before migration. Someone proposes: do not remove square brackets or change checklist state unintentionally. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Translate the text while keeping task syntax recognized by the renderer. This matters because checklist syntax may be platform-specific. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Practice 10: A relative image
Task: Review  in a moved locale folder. Someone proposes: do not assume the source path survives unchanged. Identify which words are reader language, which tokens are parsing instructions or resource references, and which target-language change is safe. Describe one mechanical test and one reader-facing test before checking the answer.
Model reasoning: Check target directory path and asset resolution before publication. This matters because the path may need a controlled remap. A high-quality answer is not only a translated sentence. It includes a protected token list, a description of expected rendered output and a check that the document still leads readers to the intended action or information. Apply the same reasoning to a different file with different paths as a transfer exercise.
Frequently asked questions
Can I translate everything inside a Markdown file?
No. Markdown mixes prose with parsing syntax, links, identifiers and often runnable code. Extract and protect each class before translation. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
Do I translate text inside backticks?
Usually not if it represents literal code, a command, a file path or an API name. An explicitly localizable quoted string inside code needs a separate approved technical workflow. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
Why do Markdown links break after translation?
The editor may have changed the href, moved the target file or altered a heading anchor. Test link destinations and their fragments from the published target location. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
Is Markdown the same on GitHub and every website?
No. Core CommonMark and platform extensions differ. A project must declare its renderer and supported features. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
Should I translate image alt text?
Yes when it carries meaningful human description, but base the wording on the actual image’s purpose and do not confuse it with the resource path. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
Do heading translations affect SEO and links?
They may affect reader search language and renderer-derived fragment IDs. Preserve meaningful wording while auditing any inbound links to anchors. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
What should happen to code fences?
Preserve valid matching delimiters, info strings and exact code contents unless the project separately authorises and tests code localization. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
Can a Markdown file render correctly and still be wrong?
Yes. A procedure can include a mistranslated prerequisite or an executable command can point to the wrong environment. Structural and meaning checks are both necessary. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
Is a Markdown linter sufficient QA?
No. Linting is useful for syntax, but it does not prove that every link resolves, commands work or translations preserve warnings. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
What do I do if the source examples are outdated?
Flag the source defect and request a maintainer decision. Translators should not silently upgrade commands as part of a language edit. As a final safeguard, test in the intended renderer and repository layout rather than assuming a local preview behaves identically to publication.
Next routes: choose the guide that owns your actual problem
This article owns Markdown formatting syntax, code-span and link-destination preservation. For software localization placeholders and plural logic, use Software Strings, Placeholders and Plural Rules (verify the current link from the series index if the destination changes). For filenames and extensions rather than Markdown parsing, read File Names, Paths, Folder Names and Extensions (navigate from the series index if necessary). Improve precise wording at the Vocabulary Learning Hub and explanatory English at How English Works. These routes have separate jobs and should not be merged into a generic translation article.
Reference and testing caveats
The primary language-neutral parsing reference is CommonMark Specification 0.31.2, 28 January 2024. GitHub Flavored Markdown and other extensions have additional rules, so check the actual toolchain before treating an extension as universal. Code snippets in this article illustrate translation boundaries; they are not instructions to execute code on a production system.