Mintlify

What is Mintlify?

Mintlify is a documentation platform that creates beautiful, customizable documentation sites. It provides built-in search, analytics, and API playground features to build modern developer documentation.

What is Lingo.dev CLI?

Lingo.dev is an AI-powered translation platform. The Lingo.dev CLI reads source files, sends translatable content to large language models, and writes translated files back to your project.

About this guide

This guide explains how to set up Lingo.dev CLI in a Mintlify documentation site. You'll learn how to scaffold a project with Mintlify, configure a translation pipeline, and view the results.

Step 1. Set up a Mintlify project

1. Install the Mintlify CLI:

   npm i -g mint
   

2. Clone the Mintlify starter template:

   git clone https://github.com/mintlify/starter.git
   

3. Navigate into the project directory:

   cd starter
   

Step 2. Create source content

1. Create a directory for storing documentation in the source locale:

   mkdir en
   

2. Create a file that contains some documentation content (e.g., en/overview.mdx):

   ---
   title: "Introduction"
   description: "Welcome to the new home for your documentation"
   ---
   
   ## Getting started
   
   This documentation is automatically translated by Lingo.dev.
   
   ## Features
   
   Our product includes powerful capabilities for modern development.
   

Step 3. Configure the CLI

In the root of the project, create an i18n.json file:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "mdx": {
      "include": ["[locale]/*.mdx", "[locale]/*/*.mdx"]
    }
  }
}

This file defines:

• the files that Lingo.dev CLI should translate
• the languages to translate between

In this case, the configuration translates MDX files from English to Spanish.

It's important to note that:

• [locale] is a placeholder that's replaced at runtime. It ensures that content is read from one location (e.g., en/index.mdx) and written to a different location (e.g., es/index.mdx).
• Lingo.dev CLI does not support recursive glob patterns (e.g., **/*.mdx). You'll need to create additional include patterns to translate files that exist within nested directories.

To learn more, see i18n.json configuration.

Step 4. Translate the content

1. Sign up for a Lingo.dev account.

2. Log in to Lingo.dev via the CLI:

   npx lingo.dev@latest login
   

3. Run the translation pipeline:

   npx lingo.dev@latest run
   

   The CLI will create an es/ directory for storing the translated content and a i18n.lock file for keeping track of what has been translated (to prevent unnecessary retranslations).

Step 5. Use the translations

1. In the docs.json file, add a languages property to the navigation object:

   {
     "navigation": {
       "languages": []
     }
   }
   

2. For each supported language, add a separate object to the array:

   {
     "navigation": {
       "languages": [
         {
           "language": "en",
           "groups": [
             {
               "group": "Getting started",
               "pages": ["en/overview"]
             }
           ]
         },
         {
           "language": "es",
           "groups": [
             {
               "group": "Getting started",
               "pages": ["es/overview"]
             }
           ]
         }
       ]
     }
   }
   

   Be aware that:

   • You'll need to replicate the entire navigation structure separately for each language.
   • Mintlify only supports a subset of the languages that Lingo.dev CLI supports.

3. Start the development server:

   mint dev
   

4. Navigate to http://localhost:3000. You should see a dropdown for switching between languages.

Known limitations

• Any UI copy that's defined in the docs.json file (e.g., sidebar group labels, search placeholder text, etc) will not be translated.

Supported languages

Mintlify only supports a subset of the languages that Lingo.dev CLI supports. For the most up-to-date list, see the official documentation.