Lingo.dev + .md/.mdx (Documentation)

Lingo.dev CLI translates Markdown and MDX documentation, blogs, and content while preserving formatting, code blocks, links, React components, and interactive elements. The CLI uses the mdx bucket as the recommended configuration for both .md and .mdx files, protecting code blocks and inline code from translation, preserving URLs while translating descriptions, maintaining frontmatter metadata, keeping React components and imports intact, translating JSX props intelligently, and working seamlessly with Next.js, Gatsby, and MDX tooling.

Quick Setup

Configure using the mdx bucket for both Markdown and MDX files:

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

Reminder: [locale] is a placeholder that should remain in the config literally, as it's replaced with the actual locale during CLI run.

Translate Documentation

npx lingo.dev@latest i18n

Translates content while preserving all Markdown formatting and MDX React components.

Markdown Content Handling

Code Block Preservation

```javascript
const message = "Hello, world!";
console.log(message);
```

Code remains untranslated while surrounding explanations get localized.

Visit [our website](https://example.com) for more details.

See the [configuration guide](./config.md) for setup instructions.

URLs and relative paths stay intact while link text gets translated.

Frontmatter Protection

---
title: "Getting Started"
date: 2024-01-15
tags: ["tutorial", "beginner"]
---

# Getting Started

Your content begins here...

YAML frontmatter remains untouched while content gets translated.

MDX Component Features

React Component Blocks

import { Alert } from "@components/Alert";

# Welcome Guide

<Alert type="info">This is important information for users.</Alert>

Regular markdown content gets translated here.

Component imports and JSX remain intact while text content gets localized.

Inline JSX Elements

Here's a <Button variant="primary">Get Started</Button> button in the text.

The component stays, but "Get Started" gets translated.

Props with Translatable Content

<VideoPlayer
  title="Introduction Video"
  description="Learn the basics in 5 minutes"
  src="/videos/intro.mp4"
/>

String props get translated while technical props remain unchanged.

Export Statements

export const title = "User Guide";
export const published = "2024-01-15";

# {title}

Content starts here...

Named exports with translatable content get localized.

Frontmatter with Components

---
title: "Getting Started"
components:
  - Alert
  - CodeBlock
---

import { Alert, CodeBlock } from "@components";

<Alert>Welcome to our platform!</Alert>

Advanced Configuration

Multiple Content Directories

"mdx": {
  "include": [
    "docs/[locale]/*.md",
    "content/[locale]/*.mdx",
    "blog/[locale]/*.{md,mdx}"
  ]
}

Note: Double asterisks (**) are not supported in glob patterns. Use single asterisk (*) for file matching within directories.

Exclude Specific Files

"mdx": {
  "include": ["docs/[locale]/*.{md,mdx}"],
  "exclude": ["docs/[locale]/drafts/*.{md,mdx}"]
}

Lock Component Props

"mdx": {
  "include": ["content/[locale]/*.{md,mdx}"],
  "lockedKeys": ["src", "href", "id", "className"]
}