Lingo.dev Docs

Appearance

Translate Interactive MDX Content with Component Preservation ​

Maintain perfect functionality in your interactive documentation with Lingo.dev's specialized MDX translation system - designed specifically for content that combines Markdown with React components.

Perfect for Interactive Content ​

Ideal for translating:

  • Interactive documentation with live examples
  • Technical guides with embedded components
  • Help centers with functional UI elements
  • Blog posts with interactive demos
  • Educational content with code playgrounds

Quick Setup ​

Create an i18n.json configuration file in your project root:

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

How It Works: Component-Aware Translation ​

Unlike standard Markdown translation, our MDX processor:

1. Intelligent Structure Parsing ​

  • AST-Based Analysis: Parses MDX into an Abstract Syntax Tree for deep structural understanding
  • Component Recognition: Automatically identifies React components and their properties
  • Smart Content Extraction: Separates translatable text from code and component definitions

2. Precision Translation ​

  • Content-Only Processing: Translates only human-readable content, not code or component props
  • Component Preservation: Maintains all JSX functionality and structure
  • Format Integrity: Preserves all MDX-specific formatting and syntax

3. Efficient Processing ​

  • Element-Level Caching: Updates only modified elements, not entire documents
  • Structural Fingerprinting: Tracks elements by structure for precise updates
  • Differential Processing: Only processes what's changed since the last translation

Cost Optimization Built-In ​

Save on translation costs with intelligent content handling:

  • Selective Translation: Only human-readable content is sent to language models
  • Code Preservation: Technical elements remain untouched, reducing token usage
  • Translation Memory: Previously translated content is reused when possible

TIP

By intelligently separating content from code, Lingo.dev significantly reduces token usage and translation costs compared to raw text approaches.

Real-World Example ​

Here's how Lingo.dev handles a typical MDX file with components:

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} />

After translation:

  • The title, heading, and paragraphs are translated
  • The code inside <CodeExample> remains untouched
  • The text inside <Highlight> is translated
  • The initialValue={42} prop remains unchanged

Developer Best Practices ​

Improve Translation Quality ​

  • Use Semantic Component Names: Name components descriptively (e.g., <CodeExample> instead of <CE>)
  • Keep Props Simple: Avoid complex nested JSX in props when possible
  • Add Context Comments: Include comments before complex sections to provide context

Optimize Your Workflow ​

  • Test Interactive Elements: Always verify component functionality after translation
  • Use Key Locking: Protect technical content with key locking
  • Leverage Fine-Tuning: Use fine-tuning for domain-specific terminology

Seamless Integration ​

MDX translation works with Lingo.dev's other powerful features:

TIP

For simpler MDX content or if you encounter any issues, you can also use our standard Markdown format, which supports basic MDX. For complex interactive content, this dedicated MDX processor provides superior results.

Need help? Contact us at [email protected]