Mintlify

Что такое Mintlify?

Mintlify — это платформа для документации, которая позволяет создавать красивые и настраиваемые сайты документации. В ней есть встроенный поиск, аналитика и песочница для API, чтобы делать современную документацию для разработчиков.

Что такое Lingo.dev CLI?

Lingo.dev — это платформа для перевода на базе искусственного интеллекта. Lingo.dev CLI читает исходные файлы, отправляет переводимый контент в большие языковые модели и записывает переведённые файлы обратно в ваш проект.

О данном гайде

В этом гайде рассказывается, как настроить Lingo.dev CLI на сайте документации Mintlify. Вы узнаете, как создать проект на Mintlify, настроить пайплайн перевода и посмотреть результат.

Шаг 1. Настройка проекта Mintlify

1. Установите Mintlify CLI:

   npm i -g mint
   

2. Клонируйте стартовый шаблон Mintlify:

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

3. Перейдите в директорию проекта:

   cd starter
   

Шаг 2. Создайте исходный контент

1. Создайте директорию для хранения документации на исходном языке:

   mkdir en
   

2. Создайте файл с каким-либо содержимым документации (например, 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.
   

Шаг 3. Настройте CLI

В корне проекта создайте файл i18n.json:

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

Этот файл определяет:

• какие файлы должен переводить Lingo.dev CLI
• между какими языками переводить

В этом случае конфигурация переводит MDX-файлы с английского на испанский.

Важно отметить:

• [locale] — это плейсхолдер, который заменяется во время выполнения. Он гарантирует, что контент читается из одного места (например, en/index.mdx) и записывается в другое (например, es/index.mdx).
• Lingo.dev CLI не поддерживает рекурсивные glob-шаблоны (например, **/*.mdx). Нужно будет создать дополнительные шаблоны include, чтобы переводить файлы во вложенных папках.

Чтобы узнать больше, см. конфигурацию i18n.json.

Шаг 4. Переведите контент

1. Зарегистрируйтесь в Lingo.dev.

2. Войдите в Lingo.dev через CLI:

   npx lingo.dev@latest login
   

3. Запустите pipeline перевода:

   npx lingo.dev@latest run
   

   CLI создаст директорию es/ для хранения переведённого контента и файл i18n.lock для отслеживания переведённых материалов (чтобы избежать лишних повторных переводов).

Шаг 5. Используйте переводы

1. В файле docs.json добавьте свойство languages в объект navigation:

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

2. Для каждого поддерживаемого языка добавьте отдельный объект в массив:

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

   Обратите внимание:

   • Для каждого языка нужно отдельно дублировать всю структуру навигации.
   • Mintlify поддерживает только часть языков, которые поддерживает Lingo.dev CLI.

3. Запустите dev-сервер:

   mint dev
   

4. Перейдите на http://localhost:3000. Должен появиться выпадающий список для переключения языков.

Известные ограничения

• Любой UI-текст, определённый в файле docs.json (например, названия групп в сайдбаре, текст placeholder поиска и т.д.), не будет переведён.

Поддерживаемые языки

Mintlify поддерживает только часть языков, которые поддерживает Lingo.dev CLI. Самый актуальный список смотрите в официальной документации.