Skip to content

Markdown Translation

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

Use Cases

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

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 Replexica:

  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 Replexica supports:

bash
npx replexica@latest show locale sources  # List available source languages
npx replexica@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 replexica@latest i18n

Replexica 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

Replexica'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: Replexica 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: Replexica 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.