How can translators and technical writers use remark CLI to inspect and format multilingual Markdown without damaging AST structure, links, code, headings or MDX components? This remark CLI localization guide explains Markdown parsing, the unified and mdast ecosystem, plugins, lint warnings, configuration files, command-line output, Unicode quality assurance and safe collaborative workflows. It is for global documentation teams, software maintainers, content engineers and editors who need language-specific prose with stable technical structure.
remark-cli is a command-line interface for working with Markdown through the remark plugin ecosystem. It can inspect, transform and format documents; it is not a translator and cannot judge whether the target-language explanation is technically correct. Some plugins change output, some report diagnostics and others add support for syntax variants. A localized document can pass every configured rule while still containing a wrong command, broken factual claim or misleading translation.
The productive approach is to distinguish reader-facing language from syntax-bearing elements, agree on the exact parser and plugin configuration, and test the output generated from each locale. Preserve code tokens, URLs, identifiers and intentional links; translate headings, prose and captions in context; and use targeted checks to detect structural drift. Treat a plugin warning as evidence to investigate, not as a command to automatically rewrite linguistic choices without human review.
Quick reference: AST structure and human meaning
- Use remark-cli to inspect, lint or format Markdown, not to certify translation quality.
- Pin parser, Markdown dialect, plugin versions and project configuration.
- Translate headings, prose, captions and appropriate labels in context.
- Preserve technical identifiers, command tokens, link targets and MDX component syntax.
- Inspect generated output for anchors, tables, Unicode and right-to-left scripts.
- Keep structural QA, language editing, safety review and release checks separate.
A safe working sequence
- Inventory document types, syntax extensions, components, plugin dependencies and output destinations.
- Create a multilingual test fixture containing realistic Markdown edge cases.
- Translate language-bearing content without corrupting syntax-bearing values.
- Run the intended CLI with explicit check or write behavior and review changes.
- Render through the actual documentation platform and test links, copying and accessibility.
- Obtain technical and native-language approval before the release is tagged.
Quick reference for a multilingual repository
A reliable remark workflow begins with a map of supported Markdown syntax, intended publishing destinations and the rules the team enforces. Syntax and style are different: an AST can tell you where a heading or code block is, but it cannot declare which translation best communicates a safety instruction. Establish a shared glossary and protected-token policy before allowing formatting or lint fixes to run across many languages.
Consider a repository with English, French and Japanese guides. All three may use the same image paths, software names and code examples, but their headings and punctuation differ. A single rule set that demands English sentence conventions can flag valid French typography as an error. Conversely, a parser configuration that ignores a required extension can misread all three variants in the same structural way.
Document which files use standard Markdown, GitHub-flavored Markdown or MDX and select matching plugins. Run a small fixture containing links, tables, images, footnotes and code before scaling to the full repository. Keep output reviews tied to the actual site renderer rather than assuming the CLI’s representation is the final reader experience.
What the remark ecosystem actually handles
remark is built around Markdown as structured content. Its plugins work with an abstract syntax tree commonly called mdast. The CLI connects these capabilities to terminal commands and automation. This structure is valuable for localization because it gives tools a way to distinguish headings, links and text nodes from raw character sequences, though plugin correctness still depends on implementation.
A naïve replacement system might change a word in a file path, the same word in a code fence and the same word in a paragraph. An AST-aware workflow can target text nodes while excluding protected constructs. That is not a blanket guarantee: links have titles and labels, image descriptions have language meaning, and some node children carry identifiers. Each transformation needs a carefully defined scope.
Review a plugin’s documented behavior before adding it. A formatter, a syntax extension and a linter solve different tasks. The presence of a large plugin ecosystem is an opportunity to build a controlled workflow, not permission to chain unrelated transformations until the output looks tidy.
Parsing versus formatting versus linting
Parsing creates a structural representation of Markdown. Formatting serializes that structure according to conventions. Linting reports deviations from selected rules. These phases can cooperate, but they have different acceptance criteria. A source file may parse and format successfully while the content remains unclear; a style rule may flag something harmless because it was designed for English prose.
Imagine a translator writes a Japanese explanation with a valid Markdown table. A Markdown formatting plugin may change surrounding whitespace. A lint plugin may require a blank line before the table. Neither operation establishes whether the procedure explains the API correctly. A third plugin could rewrite heading punctuation in ways that affect generated anchors. The same green or red diagnostic cannot cover all those dimensions.
Set separate gates for syntax validity, formatting consistency, structure preservation and editorial meaning. A team can automate the first two extensively, but should still compare output links, headings and code against approved expectations. Describe the purpose of each configured rule so editors understand what an automatic fix is supposed to achieve.
Install and invoke the right CLI
The project documentation describes installing remark-cli in a Node.js environment and using the remark command. The CLI may run as a locally installed project tool or through a package execution workflow, depending on team conventions. Pinning the package version in a project dependency lockfile makes CI and local editors more likely to see the same behavior.
A contributor might type remark . --use remark-preset-lint-markdown-style-guide to apply a chosen style-guide preset, as illustrated in project documentation. The plugin must be available and compatible in the project environment. Another command may write a transformed document with --output; such a step changes source or output files and should not be introduced silently into a review-only workflow.
Document whether the command checks or modifies files and which globs select input. A translator should know whether running the command will produce diagnostics, standard output or filesystem edits. Never promise a dry-run guarantee unless the exact invocation and installed package version have been tested.
Command options are not translatable prose
The token remark, flags such as --use, --output and --frail, and plugin package names are elements of a machine interface. Translate the explanation around them but keep the literal spelling and punctuation. Values can be more complicated: an output filename may be chosen by the author, while the package identifier passed to a plugin option must match what is actually installed.
For example, a localized README might instruct a reader to run remark --output --use remark-toc readme.md. The command illustrates a structured transformation. Changing remark-toc into a translated phrase would not make the instruction more accessible; it would make it point to a nonexistent package. A sentence can explain in Spanish what the plugin does while still showing the correct command.
Test sample commands by copying them from the final translated site rather than from the source editor. Typography engines may substitute curly quotation marks, non-ASCII dashes or invisible directional marks. Even excellent translations fail their practical purpose if the reader cannot run the documented command.
The Markdown abstract syntax tree
mdast represents Markdown constructs as structured nodes such as headings, paragraphs, links, code blocks and emphasis. The exact structure depends on parser extensions and plugins. For localization, the advantage is the ability to reason about a document’s parts instead of blindly editing every occurrence of a phrase. The limitation is that structural categories do not automatically encode the semantics of technical instructions.
A heading node has a depth and child text. A link node has a destination and human-facing label. Translating the label is often appropriate, while altering the destination requires a separately approved decision. A code block should generally remain exact, yet its surrounding explanation is language-bearing. A list’s child paragraphs need translation, but the step order may carry operational meaning.
Inspect representative AST output when building custom transformations. Include tests for inline code in a translated paragraph and labels containing punctuation from several scripts. The goal is not to expose a syntax tree to ordinary readers; it is to give the publishing system a reliable boundary between prose and technical structure.
Text nodes are not all equivalent
Even inside text-like nodes, context affects what should be translated. A button label in a screenshot caption, an acronym expansion, a literary quotation and a warning message require different treatments. Structural extraction can isolate a segment from code, but domain knowledge is still needed to decide how its wording relates to other parts of the manual.
Consider an API document with an English status string that the product literally returns to clients. The sentence describing that status can be translated; the quoted status token might be a machine value that must remain exact. In another section, the same phrase could be the user-visible button text in a localized interface. Automatic categorization by visible characters alone would miss the difference.
Attach context to extracted segments: source location, enclosing node type, product version, screenshots and relevant terminology. Ask a technical reviewer when one phrase could be both a literal identifier and natural-language text. Reliable translation treats context as part of the content.
GitHub-flavored Markdown features
Many repositories use GitHub-flavored Markdown conventions for tables, task lists, autolinks and other constructs. Parsing support should be selected deliberately, for example through appropriate plugins such as remark-gfm where required by the project. Without matching syntax support, a formatter may interpret intended structure incorrectly or serialize it into unexpected text.
A localization reviewer might see a task-list marker alongside a French instruction. Replacing the marker with a translated symbol can destroy task-list rendering. Similarly, a table separator row is formatting syntax, not a sentence. The visible table headers and explanatory cell content need translation, but the structural separators and data relationships must remain intact.
Use a fixture containing the exact Markdown features present in the repository. Render after processing and compare the generated structure, not merely the source lines. If the site uses a different GitHub Markdown renderer or version, test that destination too; remark’s processing and the final platform’s interpretation are related but not interchangeable.
MDX demands an explicit parser policy
MDX combines Markdown-like prose with component syntax and JavaScript expressions. That mixture raises the risk of treating code as ordinary text or corrupting a component’s props during translation. Do not assume a basic Markdown plugin chain fully understands MDX; choose and test a toolchain designed for the actual syntax used in the project.
A documentation page may include a component that renders tabs for two programming languages. The tab labels can be reader-facing, while the component name and prop keys are structural identifiers. A global replacement that translates a prop key could break the component or make the intended panel disappear. A source file may still display as readable text in a plain editor while failing at build time.
List the MDX components and the props that are safe to localize. Test nested elements, inline expressions and code fences with the production compiler. When an AST transformation cannot preserve the component boundary reliably, exclude that file type from the automated step rather than guessing at the parser’s behavior.
Configuration files and plugin scope
remark-cli can use configuration to load plugins and settings, reducing long repeated commands. This is valuable in a multilingual repository where consistent lint behavior matters. However, each configured plugin has a scope: some check all Markdown files, others transform content or depend on extensions. A change to the shared configuration can affect every language even when no translated source file changed.
Imagine a team adds a rule to enforce an English-style heading convention. The change may suddenly produce warnings in Arabic, German and Thai editions for reasons unrelated to reader quality. The correct response is to decide whether the rule is structural, stylistic across languages or specifically English-oriented. Separate configuration or controlled exceptions may be warranted.
Version the configuration and document why each rule exists. Review configuration diffs as carefully as prose changes. For a new language, run a fixed sample to establish how existing rules behave before interpreting a flood of warnings as evidence that the translators have done poor work.
Choosing plugins by reader problems
Plugins should be selected to address a concrete reader or maintenance risk: inconsistent headings, unsupported syntax, malformed links, unhelpful tables, or unwanted formatting drift. Do not treat plugin count as an indicator of quality. Every additional transform introduces a possible interaction with other plugins and with target-language conventions.
A team concerned about predictable navigation might use a table-of-contents transformation, while a team concerned about Markdown conventions might use a lint preset. Those goals are distinct. A plugin that rewrites heading text to generate a table of contents must be tested against translated headings and the website’s anchor-generation algorithm; a lint preset should not be allowed to rewrite meaning in pursuit of consistent punctuation.
Map every plugin to an acceptance criterion and a test case. If no one can explain why a plugin is needed, remove it from the critical release path until its purpose is established. Small, comprehensible tooling is usually more reliable than an impressive stack nobody understands.
Syntax preservation in inline code
Inline code contains content that should usually stay literal: command names, file paths, package identifiers and property keys. Translators can explain those tokens, but should not localize them unless the value is explicitly illustrative and approved for replacement. An AST-aware process can recognize inline code nodes, making it possible to protect many such values automatically.
A French tutorial might say ‘Set the cache_dir property.’ The property name remains cache_dir; changing it into a French phrase would make the instruction false. If the prose instead shows a fictional user-provided value such as sample-project, a locale-specific example could be acceptable, but only if the changed value remains consistent across the command and expected output.
Audit inline code separately from block code. A translator may faithfully preserve fenced commands yet accidentally alter a small literal token embedded in a long explanatory sentence. Protecting both kinds is a practical way to reduce high-impact translation errors.
Fenced code and information strings
Fenced code blocks may specify a language for syntax highlighting. The information string, fence markers and executable content are different from prose. A formatter can change spacing or fence style; whether that is harmless depends on the target renderer and the code inside. Preserve commands and test extraction from published pages when code has operational meaning.
A Python example inside an English tutorial may be identical in the Japanese edition except for comments. Some comments can be translated safely, but a code example whose comments influence parsing or documented output may require extra care. It is not enough to classify every character between fences as untranslatable or, conversely, every English-looking word as a sentence to replace.
Use a code owner for executable snippets and run examples where practical. Compare tokens for shell commands, YAML keys, JSON property names and API paths. In output, confirm that the highlighting class, copy button and line wrapping do not alter the code pasted into an actual tool.
Links: labels, paths and destinations
A Markdown link has a human-visible label and a destination. These should be reviewed independently. Labels normally need translation for clarity and accessibility; URLs may remain unchanged, point to an equivalent localized page or carry locale parameters. Changing a URL is a content-routing decision that should be verified rather than inferred from the translated label.
A Korean manual might replace the label ‘Installation guide’ with a Korean phrase while retaining an English vendor URL if no Korean equivalent exists. Another link might switch to a verified Korean page covering the same software version. In both cases the reader should know what to expect. Rewriting an anchor path without confirming the target page is a common source of broken navigation.
After formatting, inspect link labels and destinations. Verify both reachability and semantic equivalence. A lint rule that checks Markdown syntax cannot determine whether the destination’s advice is authoritative or current.
Image descriptions and alt text
Image descriptions are reader-facing language and should be localized when the image conveys information. The file path is an operational reference and may be shared across locales. A translator must decide whether an image with embedded source-language labels needs a localized counterpart or an additional explanation. Merely translating the filename is not useful.
A diagram showing a deployment sequence may use arrows and English labels. If the labels matter to understanding, the localized text should explain or replace them without altering the sequence. The alt description must describe the actual process, not a generic phrase such as ‘diagram’. If a localized image is produced, verify that the new file exists and its references update consistently.
Inspect images in the final published site, including screen-reader alternatives and narrow viewports. Some Markdown processors preserve image syntax while website templates supply captions separately. The localization workflow needs to include both surfaces.
Heading levels and document outlines
Heading markers indicate hierarchy. Translating a heading does not justify changing its level unless the content structure itself has been revised with editorial approval. Lint rules may detect skipped levels or inconsistent style, but a syntactically neat hierarchy can still be logically confusing if headings describe different concepts than their sections.
A guide might present ‘Configure authentication’ as a main section followed by ‘Rotate the secret’ as a subsection. A translation that subtly changes the first heading into ‘Log in’ can misrepresent the section’s purpose. If a formatter also flattens the heading levels, the reader loses both conceptual and structural cues.
Review the outline as a list separate from the full prose. Read only the headings and ask whether they form a coherent learning sequence. Then inspect generated anchor links, because heading translations may affect destination fragments on publishing platforms.
Repeated headings and generated anchors
Markdown hosting platforms often derive link fragments from heading text. Repeated headings may receive disambiguating suffixes, and different renderers may handle punctuation or Unicode differently. Translating the heading can change its generated fragment even if no Markdown syntax is broken. This is a navigation risk rather than necessarily a lint error.
An English README may have two sections called ‘Examples.’ A translator changes them to an equivalent target-language word, but links generated earlier still point to English fragments. Automated table-of-contents entries may update, while hand-written links in release notes remain stale. A reviewer must inventory both generated and manual references.
Choose a stable-anchor policy for high-value links and test it in the final renderer. Do not assume that remark, a Git hosting platform and a separate documentation site all use the same slug algorithm. Each may require its own integration check.
Lists, indentation and procedural meaning
Markdown lists encode grouping and nesting through markers and indentation. A formatter may normalize these characters while keeping the same tree, but translators must preserve the order of procedural steps and the relationship between conditions and actions. A translation that moves a condition out of its nested list can change what the instruction requires.
Suppose a security procedure has three steps and a warning nested under step two. If the warning is moved to the end of the document during editing, a reader may act before seeing it. The Markdown can still pass structural checks. A target-language editor should inspect the rendered workflow and confirm that prerequisites, actions and expected results remain adjacent.
Use a paired checklist that verifies both AST-level nesting and domain-level procedure order. Formatting automation should never become permission to reorder operational steps just to make sentences flow naturally.
Tables and translated row relationships
Markdown tables are compact but can be fragile when language changes expand label lengths. A GFM-aware parser can preserve their structure, yet an output website may wrap cells awkwardly or hide headings at mobile widths. Maintain the connection between each data value, header and explanatory note.
A pricing table might show the period, currency and eligibility condition in separate columns. Translating the labels without maintaining the row relationship can alter a real-world decision. Another table may contain configuration defaults that must stay literal while descriptions change. The correct approach distinguishes technical values from explanation rather than copying the entire table into a translation system as unstructured text.
Review tables in the renderer with realistic content lengths. Confirm numbers, units, currency formatting and link destinations. A green lint result does not establish that a wide translated table remains usable or accessible.
Footnotes and syntax extensions
Footnotes can carry caveats, sources and explanatory context. Their Markdown representation depends on syntax support. If the parser treats a footnote definition as plain text, an automated transformation may detach it from the intended reference or expose raw markers to readers. Establish whether the publishing platform and configured plugins support the same extension.
A scientific explanation may attach a footnote qualifying the sample size. Losing that reference changes how readers interpret the claim even if the main paragraph is translated accurately. A localization editor should follow each footnote marker through to the actual note in the generated output and check the wording.
Compare note counts, destination identifiers and reference order between language editions. When a feature cannot be represented reliably in the chosen publishing path, choose a transparent alternative such as an explicit nearby note rather than silently dropping important context.
Formatting and the risk of surprising diffs
Automated output can rewrite whitespace, list markers, emphasis markers and other stylistic details. Some changes are harmless, but large formatting diffs make it difficult to see the translator’s actual decisions. A team’s review process should separate prose edits from mechanical normalization whenever possible.
Imagine a pull request that changes six translated paragraphs but reformats every Markdown file in the repository. Reviewers can no longer easily verify whether commands and references were preserved. The problem is not only aesthetics; hiding a substantive change inside broad mechanical churn increases the chance that an error reaches publication.
Use a consistent pinned formatter configuration and apply it before translating or as a distinct reviewable change. Favor targeted file globs and avoid unnecessary global rewrites. Keep generated files distinct from hand-authored source where that improves auditability.
Diagnostics and severity
remark-cli reports messages generated by configured processors and plugins. Some warnings concern style, others indicate likely structural problems. The --frail option is documented for treating warnings as a failure condition, but teams should decide which warnings are appropriate release blockers. Linguistic style conventions designed for English may create noise in other languages.
A lint warning about heading spacing might be mechanical and easy to fix. A warning associated with a broken reference or invalid syntax may justify blocking publication. An unrecognized spelling in a product name may be correct. A uniform policy to autofix everything can damage intentional localized phrasing and technical identifiers.
Classify diagnostics by their impact on readers, and supply a documented path for justified exceptions. Keep the original error text in technical tickets so engineers can reproduce it, with a translated explanation if needed. Measure whether the rule improves quality rather than merely reducing warning counts.
Localization policy for writing style
Language-specific editorial style matters: capitalization, punctuation, sentence length, formal address and word spacing vary. A generic Markdown linter should not pretend that one language’s grammar is universal. Structural rules can often be shared, while linguistic rules may need a locale-specific configuration or a human review rather than a programmatic rewrite.
English headlines may favor title case, while another language’s headings conventionally use sentence case. Applying an English-only rule across all languages can make the target unnatural. A French nonbreaking-space convention before certain punctuation marks may be appropriate even if a generic formatter reports unusual whitespace.
Create a style guide that explains intended reader outcomes, not just a list of forbidden characters. Separate the language editorial layer from the structural Markdown layer. Test the actual output at common viewport sizes so that typography changes remain legible.
Unicode normalization and lookalike symbols
Unicode makes it possible to write natural documentation in many scripts, but visually similar characters can be operationally different. A Latin letter and a Cyrillic lookalike may appear identical in a package name but resolve to different text. Composed and decomposed accents can also differ at the code-point level while rendering similarly. Normalize with a clear policy and respect protected identifiers.
A shell command --output may be rendered with a typographic dash or a hidden directional mark after being pasted into a document editor. A Japanese heading can be perfectly valid Unicode and should not be transliterated simply to satisfy a tool designed for ASCII. The critical distinction is between human-facing text and code or link identifiers.
Run copy-and-paste tests on rendered commands, compare protected tokens byte-for-byte where necessary and check heading anchors in the publishing platform. Use warnings to investigate rather than to strip non-Latin characters from legitimate prose.
Right-to-left Markdown considerations
Arabic and Hebrew content commonly places left-to-right code, numbers, package names and URLs inside right-to-left sentences. Rendering can produce confusing punctuation and visually reordered snippets even when the underlying source is valid. A structural Markdown processor does not automatically solve every bidirectional layout issue in the final HTML or app.
An Arabic guide may explain a JavaScript command that must be copied exactly. The visible words can read right to left, but the code span should remain a stable left-to-right unit. Inserting invisible characters into the command itself can create a hidden copy failure, while omitting appropriate isolation can leave punctuation in a confusing position.
Inspect the actual published output and copy representative commands into the target terminal. Test lists, tables, footnotes and navigational links in a right-to-left browser context. Use semantic directionality controls in the hosting environment where appropriate instead of altering executable tokens.
Machine translation needs structural boundaries
A translation service may be useful for drafting prose but should not receive a Markdown document as one undifferentiated string. Code, links, syntax markers and identifiers can be altered if the service interprets them as ordinary language. An AST-based extraction stage can protect many such regions, but it must preserve enough context for accurate translation.
Translating a link label in isolation may be straightforward, while translating an incomplete clause separated across emphasis nodes may produce ungrammatical output. Likewise, a technical term used in a heading should align with its occurrence in the paragraph below. A robust workflow joins related context for the translator and then reconstructs the verified structure.
Keep a protected-token list and validate both the translated text and the reconstructed Markdown. Use human review for ambiguity, safety claims and terminology. Do not market a parser or plugin as an accuracy guarantee for high-stakes instructions.
Custom transforms should be testable
Some teams write custom plugins to enforce documentation conventions or extract text for localization. A useful plugin should have a precise contract: input node types, permitted modifications, expected output and error behavior. Review its handling of nested syntax, whitespace, links and Unicode before allowing it to process an entire multilingual repository.
A custom plugin that rewrites every heading to insert a navigation prefix may produce duplicated or awkward prefixes in languages that order phrases differently. One that identifies text nodes might accidentally miss alt text or accidentally process inline HTML. A fixture covering diverse node types and scripts reveals these defects before a release.
Maintain unit tests for expected AST changes and integration tests for final rendered output. Record the plugin version and its configuration. When uncertain, design a read-only diagnostic mode before enabling writes, so editors can see what would be affected.
Version changes and dependency review
Remark and its plugins evolve, as do Node.js environments and hosting renderers. An update can alter parsing, formatting or diagnostics even when source content has not changed. Localized editions may be especially sensitive if plugins have implicit assumptions about punctuation or character boundaries.
A repository update that changes the Markdown parser may alter the generated anchor for an accented heading. Another update may flag a list style that was previously accepted. If a team upgrades dependencies and edits translations in the same release, it becomes harder to identify which change caused a regression.
Pin and review package versions, run a multilingual fixture after upgrades and document any output migration. Do not infer compatibility from the name of a plugin alone. A release note should explain meaningful changes to the processor or publication environment that readers and maintainers may notice.
Search intent and user-facing page titles
Translated documentation performs better for readers when titles state a problem or action plainly. Keep product and plugin identifiers where necessary, then write natural target-language phrases around them. A page focused on AST transformations should not use the same generic title as one focused on prose linting or HTML deployment. Distinct answers help readers choose the right guide.
A maintainer searching for a way to protect code spans during translation needs a specific explanation, not another generic promise of ‘professional localization.’ A documentation editor searching for remark-cli lint warnings needs rule behavior and examples. Reflect those intents in opening paragraphs, navigable headings and short task-oriented descriptions.
Check that cross-links genuinely lead to related topics and that search results do not advertise abilities the tool lacks. Avoid unsupported claims about traffic or rankings. Practical accuracy and clear distinctions among guides are better long-term editorial choices than repeated keywords.
A complete release case study
Imagine a developer portal containing English source Markdown, French and German translations, GFM tables and a handful of MDX components. First catalogue file types, package versions, plugins, link routes and protected tokens. Establish separate lint rules for Markdown structure and human-language style. Create a sample page with headings, tables, images, code and cross-references in each locale.
Next translate prose, descriptive labels and captions while preserving package names, CLI flags, API fields, component syntax and verified URLs. Run remark-cli with the project configuration, inspect the resulting diffs, and rebuild through the actual documentation site renderer. Test that links and headings still work and that MDX components receive the intended language-specific labels.
Finally use independent readers to assess clarity, have a developer execute selected code samples and verify mobile, accessibility and Unicode rendering. Record the source revision, plugin versions and review decisions. The release is ready when both structure and meaning are defensible, not simply when the linter stops printing warnings.
Troubleshoot the earliest divergence
When an output changes unexpectedly, locate the first transformation that differs from expectations. Examine input encoding, selected extensions, plugin order, configuration, file selection and destination renderer. Distinguish a parser problem from a serializer change and a website theme problem from a translation issue. This order is faster than rewriting correct text to compensate for an unknown tooling defect.
If a table becomes plain text, check GFM support. If a component disappears, check MDX awareness. If anchors change, compare heading text and the site’s slug algorithm. If commands fail only after publication, copy them from rendered output and inspect hidden characters. If warnings multiply in one language, review whether a rule embeds an English-language assumption.
Once fixed, add a regression case to the multilingual fixture. A repeatable check catches future changes before they affect every translated page, while a one-off manual fix tends to disappear from institutional knowledge.
What automation cannot responsibly decide
No Markdown tool can determine whether an emergency instruction is safe, whether a research claim is supported or whether a translated contractual sentence has the correct legal scope. Those are content decisions. Tools can preserve structure and detect mechanical defects, but ambiguous meaning needs a knowledgeable human reviewer.
Suppose the English source says a procedure ‘may’ restore data. A translation that guarantees restoration is wrong even if every Markdown node is preserved. Conversely, a source typo that creates dangerous ambiguity should be escalated rather than faithfully replicated without comment. Technical structure is a vessel for meaning, not a substitute for it.
Use clear review boundaries and make changes traceable. A professional workflow allows translators to flag unclear source material, engineers to verify commands and authors to correct factual issues before the target edition is released.
Frequently asked questions
Does remark-cli translate Markdown?
No. It processes Markdown with configured parsing, formatting and lint plugins. Translation is a separate language task, and the tool cannot assess fidelity or factual correctness on its own.
What is mdast?
It is a structured representation of Markdown constructs such as headings, paragraphs, code and links. Plugins can work on that structure rather than treating all content as an undifferentiated string.
Should I translate code blocks?
Usually not the executable syntax. User-facing comments or illustrative values may be candidates, but changes should be approved and examples tested. Preserve language tags, technical keys and copied commands.
Can remark-cli process MDX safely?
Only with a compatible and tested syntax/toolchain. Basic Markdown parsing should not be assumed to understand arbitrary MDX components or expressions.
Is `–frail` suitable for every locale?
It can make warnings fail a run, but the usefulness depends on configured rules. English-only stylistic rules can be inappropriate for other languages. Separate structural blockers from language-specific editorial judgments.
Why are my heading links broken after translation?
Anchor fragments can be generated from heading wording and differ across hosting platforms. Test translated headings against the actual destination renderer and manage stable IDs where needed.
Will a green lint run prove that my translation is correct?
No. It demonstrates only the tested technical and style rules. Meaning, usability, safety, source fidelity and accessibility still require human review.
How do I stop a formatter from rewriting the whole repository?
Use pinned configurations, targeted file selection and a clearly documented check-versus-write workflow. Review any write-mode output in a separate, understandable diff before merging.
Final checklist
- The opening paragraphs answer a real localization and Markdown question.
- The project’s syntax variant, CLI version and plugin configuration are reproducible.
- Protected code, URLs, package names and identifiers are unchanged unless explicitly approved.
- Heading hierarchy, generated anchors, links, tables and MDX components work.
- Formatting changes are reviewed separately from translation decisions.
- Unicode scripts, bidi text, inline code and copied commands are tested.
- Accessibility, local-language clarity and safety claims have human approval.
- The release records exact source and tool revisions for future maintenance.
Primary sources and next reading
See the official remark-cli documentation, remark ecosystem overview, and plugin guidance for command behavior and syntax-tree workflows. For complementary checks, eduKateSG also covers markdownlint-cli2 structure checks. Verify installed options and plugin compatibility before applying automated edits.