Lingo.dev Docs

Appearance

Markdown Translation ​

Translating Markdown files is crucial for multilingual documentation, blog posts, and other content-heavy projects.Lingo.dev handles this with ease, preserving your document structure while translating the content.

Use Cases ​

  • Technical documentation
  • Blog articles
  • README files
  • Wikis
  • Product guides

TIP

Lingo.dev supports translating standard Markdown files (.md) but also Markdown for components (MDX) (.mdx). Both formats are supported out of the box and there is no extra configuration required.

Setting Up ​

First, configure your i18n.json:

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

This setup tells Lingo.dev:

  1. Your source language is English;
  2. You want translations in Spanish, French, and German;
  3. Your Markdown files are in the docs folder, in language-specific subfolders.

Available Languages ​

To see what languages Lingo.dev supports:

bash
npx lingo.dev@latest show locale sources  # List available source languages
npx lingo.dev@latest show locale targets  # List available target languages

Use these to choose the right locale codes for your project.

Translating ​

Run the translation process:

bash
npx lingo.dev@latest i18n

Lingo.dev will:

  1. Read your source Markdown file (e.g., docs/en/guide.md);
  2. Identify new or changed content;
  3. Translate it to your target languages;
  4. Update or create the target Markdown files (e.g., docs/es/guide.md, docs/fr/guide.md, docs/de/guide.md).

Why This Approach Works ​

Lingo.dev's Markdown translation is effective because:

  1. It preserves Markdown syntax, ensuring your document structure remains intact;
  2. It uses AI to understand context, giving more accurate translations for technical or domain-specific content;
  3. It's incremental, only translating what's new or changed, which is perfect for frequently updated docs.

Pro Tips ​

  1. Front Matter: Lingo.dev handles YAML front matter in Markdown files. It'll translate the content while preserving the structure:

    markdown
    ---
title: Getting Started
description: Learn how to use our product
---

# Welcome to Our Product

This guide will help you get started...

  2. Links and Images: Lingo.dev preserves Markdown links and image syntax, only translating the alt text:

    markdown
    [Visit our website](https://example.com)

![An example image](./images/example.png)

By leveraging these features, you can maintain comprehensive multilingual documentation or content, keeping it in sync across all languages with minimal effort. This approach works well whether you're documenting an open-source project, writing technical guides, or managing a multilingual blog.