MDX

MDX is an extended version of Markdown that allows JSX components and JavaScript expressions alongside standard Markdown content. It is commonly used in documentation frameworks like Docusaurus and other component-driven content sites.

Smartling's MDX parser supports MDX v3 syntax.

Content parsing

What is ingested for translation

Smartling extracts the following content from MDX files as translatable strings:

Text content

Paragraph text, headings at all levels, list items (ordered and unordered), blockquote text, and table cell text. Inline formatting like bold, italic, strikethrough, subscript, and superscript is converted to HTML tags (e.g., **bold** becomes <strong>bold</strong>) during upload and converted back to Markdown syntax when you download the translated file.

Links

The visible text inside links is translatable. URLs are preserved as non-translatable placeholders. For example, in [Learn more](/docs/guide), "Learn more" is extracted for translation and /docs/guide is preserved.

Inline code

Strings containing inline code are extracted for translation. Backtick-wrapped code (e.g., `npm install`) appears in the CAT tool as a non-editable placeholder within the string. Translators can see the code and reposition it, but cannot edit the content inside.

YAML front matter

String fields in YAML front matter blocks (such as title, description, and string values in arrays like tags) are ingested for translation. Numbers, booleans, dates, and non-string values are skipped. YAML front matter extraction is enabled by default for MDX files. You can disable it with the yaml_front_matter directive.

JSX component attribute values

Smartling translates attribute values for a default set of JSX attributes: title, alt, label, description, and caption. For example, in <Callout title="Before you begin">, the value "Before you begin" is extracted for translation. You can customize which attributes are translated using the include_translatable_attributes and exclude_translatable_attributes directives.

Text inside JSX components

Content within JSX component tags is extracted for translation, including any nested Markdown formatting. For example, in <Note>Make sure you have **Node.js 18+** installed.</Note>, the full text with bold formatting is extracted.

HTML elements

All HTML-like tags (<div>, <span>, <a>, <img>, etc.) are treated as React/JSX elements in MDX. Their structure and tag names are preserved. Their attribute values follow the same whitelist rules as custom JSX components. Expression-based attributes like style={{ color: 'red', fontWeight: 'bold' }} are not extracted — they are JSX expressions, not string literals, and are preserved as-is.

What is not ingested for translation

The following content is preserved as-is in the translated file and not sent for translation:

• Code blocks (fenced with triple backticks)
• Inline code content — the text inside backticks is not editable by translators. It appears as a repositionable placeholder within the translated string.
• Import and export statements
• JSX expressions (e.g., {variable}, {5 * 5}, {await fetch(...)})
• JSX component names and structure
• Non-whitelisted JSX attribute values (e.g., type="info", href="...", src="...")
• Expression-based attributes (e.g., style={{ color: 'red' }}, onClick={handler})

Keys and variants

Smartling generates keys automatically as sequential unit IDs: unit-1, unit-2, etc. YAML front matter fields use composite keys such as unit-1#title, unit-1#tags[0], and unit-1#description.

Variants are enabled by default using the REPETITION_INDEXED strategy, which creates indexed variants for repeated strings. This means that if the same string appears multiple times in your file, each occurrence is tracked separately. You can change this behavior with the variants_enabled and variants_strategy directives.

Placeholders

When Smartling processes your MDX file, JSX components and HTML elements are converted to placeholder tags that translators can work with in the CAT Tool:

• Components with children (e.g., <MyBox>enterprise ready</MyBox>) become <span> tags with an ID attribute. The text inside is translatable, and the translator can reposition the span tags. For example: <span id="1">enterprise ready</span>.
• Self-closing components (e.g., <Badge />) become non-editable placeholders. Translators can reposition these placeholders but cannot modify them.
• Markdown images (e.g., ![alt text](image.png)) are converted to a single placeholder. The alt text is embedded inside the placeholder and is not independently translatable. To make image alt text independently translatable, use JSX syntax instead: <img src="image.png" alt="alt text" />.

If your MDX content contains additional placeholder patterns (e.g., {0}, %s, or custom patterns), use the placeholder_format or placeholder_format_custom directives to ensure they are correctly ingested as placeholders.

When you download the translated file, all placeholder tags are converted back to their original JSX components and HTML elements.

Known limitations

• JSX expressions are not translatable. Content inside curly braces (e.g., {variable}, {await fetch(...)}) is JavaScript, not text. It is preserved as-is.
• Expression-based attributes are not translatable. Attributes that use JSX expressions (e.g., style={{ color: 'red' }}) are preserved as-is because they contain JavaScript, not string literals.
• Only whitelisted attributes are translated. JSX attribute values are only translated if the attribute name is in the default set (title, alt, label, description, caption). To translate additional attributes, use the include_translatable_attributes directive.
• Markdown image alt text is not independently translatable. In ![alt text](image.png), the alt text is embedded in the placeholder and not extracted as a separate string. To make image alt text independently translatable, use JSX syntax instead: <img src="image.png" alt="alt text" />.
• Complex nested structures (e.g., JSX inside lists, deeply nested components) are supported but may use full-block reconstruction instead of granular patching during translation delivery.
• MDX v3 syntax required. Smartling's parser is built for MDX v3, which has stricter spacing requirements than v2. Blank lines are required before and after JSX blocks that are mixed with Markdown content.

Directives

MDX files support the following directives. Directives can be provided via API parameters or default directive templates. For details on how to apply directives, see how to apply directives. MDX does not support inline directives, meaning you cannot place directives directly inside your .mdx files.

Directives are specified in the following format:

API Parameter

smartling.[directive_name] = [value]

MDX-specific directives

Process YAML Front Matter

Include Translatable Attributes

Exclude Translatable Attributes

Standard directives supported by MDX

Standard Placeholder Format

Custom Placeholder Format

Variants Enabled

Variants Strategy