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 standard Markdown files (.md). For JSX-enhanced Markdown, see our dedicated MDX documentation.

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.