Lingo.dev Docs

Appearance

MDX Translation ​

MDX combines the power of Markdown with JSX, allowing you to use React components within your content. Lingo.dev offers specialized support for MDX files, optimizing the translation process while preserving component structure and functionality.

Use Cases ​

  • Interactive documentation
  • Technical content with embedded components
  • Help centers with UI elements
  • Blog posts with interactive elements
  • Educational content with embedded examples

How Lingo.dev Handles MDX ​

Lingo.dev's approach to MDX translation is designed for efficiency and precision:

Deep Structure Analysis ​

Unlike simple text-based translation (like Markdown), Lingo.dev:

  1. Deeply destructures MDX content - We parse the MDX into an Abstract Syntax Tree (AST), allowing us to understand the structure beyond just text.
  2. Preserves component integrity - JSX components and their props remain untouched during translation.
  3. Translates only content nodes - Only the actual content gets translated, not code or component definitions.

Caching ​

Our caching mechanism is designed to save time and resources:

  1. Element-level caching - If you change just one word in a paragraph, only that element gets retranslated, not the entire file.
  2. Structural fingerprinting - We identify elements by their structure and position, enabling precise updates.
  3. Differential processing - Only modified content triggers new translations.

Cost Optimization ​

Lingo.dev is designed to be cost-effective:

  1. Selective localization - Technical elements, code blocks, and component definitions aren't sent for translation, saving tokens and costs.
  2. Smart token usage - We optimize the content sent to language models to reduce unnecessary token consumption.
  3. Translation memory - Previously translated content is reused when possible (when Lingo.dev-managed localization is used).

TIP

By not localizing code elements and technical content that should remain unchanged, users can save significant costs in tokens and processing time.

Setting Up ​

Configure your i18n.json to include MDX files:

json
{
  "version": 1,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "mdx": {
      "include": ["docs/[locale]/*.mdx"]
    }
  }
}

Technical Implementation ​

Lingo.dev uses a parser chain that:

  1. Parses MDX into an AST
  2. Analyzes the structure to identify translatable content
  3. Sends only the relevant parts for translation
  4. Reconstructs the MDX with translated content while preserving structure

This approach ensures your components continue to work properly after translation, with no changes to functionality.

Best Practices ​

  • Keep component props simple - Complex nested JSX in props may affect translation quality
  • Use semantic component names - Clear names help the translation engine understand context
  • Test interactive elements - Always verify that interactive components work after translation

Integration with Other Features ​

MDX translation works seamlessly with other Lingo.dev features:

Example ​

Here's how a simple MDX file with components might be handled:

mdx
---
title: Interactive Tutorial
---

# Getting Started with Components

This is a simple paragraph explaining the concept.

<CodeExample language="javascript">
  function hello() {
    console.log("Hello, world!");
  }
</CodeExample>

The above code demonstrates a basic function. <Highlight>Try it yourself!</Highlight>

<InteractiveDemo initialValue={42} />

When translated, only the actual content text gets processed while preserving the component structure and code.

TIP

If you encounter an MDX use case that we don't support, please email us immediately at [email protected]. For simpler MDX content, you can also try using the standard Markdown format, which supports basic MDX on a fundamental level. This dedicated MDX format is our specialized, advanced solution for complex MDX content with interactive components.

Learn More ​