Mintlify

什么是 Mintlify？

Mintlify 是一个文档平台，可创建美观且可自定义的文档站点。它内置搜索、分析和 API playground 等功能，帮助构建现代化的开发者文档。

什么是 Lingo.dev CLI？

Lingo.dev 是一个由 AI 驱动的翻译平台。Lingo.dev CLI 会读取源文件，将可翻译内容发送给大型语言模型，并将翻译后的文件写回到您的项目中。

关于本指南

本指南介绍如何在 Mintlify 文档站点中配置 Lingo.dev CLI。您将学习如何使用 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. 通过 CLI 登录 Lingo.dev：

   npx lingo.dev@latest login
   

3. 运行翻译流水线：

   npx lingo.dev@latest run
   

   CLI 会创建一个 es/ 目录用于存储翻译后的内容，并生成一个 i18n.lock 文件，用于记录已翻译内容（以防止重复翻译）。

步骤 5. 使用翻译结果

1. 在 docs.json 文件中，为 navigation 对象添加一个 languages 属性：

   {
     "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. 启动开发服务器：

   mint dev
   

4. 访问 http://localhost:3000。你应该能看到用于切换语言的下拉菜单。

已知限制

• 在 docs.json 文件中定义的任何 UI 文案（如侧边栏分组标签、搜索占位符文本等）都不会被翻译。

支持的语言

Mintlify 仅支持 Lingo.dev CLI 支持语言的子集。最新支持列表请参见官方文档。