MDX - Lingo.dev CLI

什么是 MDX？

MDX 是一种将 Markdown 与 JSX 结合的格式，允许您在 Markdown 内容中直接使用 React 组件。它通常用于文档网站和内容丰富的 Web 应用程序。

例如：


---

title: "餐厅评论：Bella Vista"
description: "我们在市中心新开的意大利餐厅的用餐体验"
author: "not-localized-author"

---

# 在 Bella Vista 的晚餐

我们终于尝试了上个月在主街新开的意大利餐厅。

## 氛围

餐厅有一种温暖、令人愉悦的氛围，包括：

- **柔和的灯光**，营造出亲密的环境
- *背景播放的柔和爵士音乐*

什么是 Lingo.dev CLI？

Lingo.dev CLI 是一个免费的开源 CLI，用于使用 AI 翻译应用程序和内容。它旨在取代传统的翻译管理软件，同时与现有的管道集成。

要了解更多信息，请参阅概述。

关于本指南

本指南解释了如何使用 Lingo.dev CLI 翻译 MDX 文件。

您将学习如何：

从头开始创建项目
配置翻译管道
使用 AI 生成翻译

前提条件

要使用 Lingo.dev CLI，请确保已安装 Node.js v18+：

❯ node -v
v22.17.0

第 1 步：设置项目

在项目目录中，创建一个 i18n.json 文件：

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

此文件定义了翻译管道的行为，包括要翻译的语言以及文件系统中可本地化内容的位置。

要了解更多可用属性，请参阅 i18n.json。

步骤 2. 配置源语言环境

源语言环境 是指您的内容所使用的原始语言和地区。要配置源语言环境，请在 i18n.json 文件中设置 locale.source 属性：

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

源语言环境必须以 BCP 47 语言标签的形式提供。

有关 Lingo.dev CLI 支持的语言环境代码的完整列表，请参阅支持的语言环境代码。

步骤 3. 配置目标语言环境

目标语言环境 是指您希望将内容翻译成的语言和地区。要配置目标语言环境，请在 i18n.json 文件中设置 locale.targets 属性：

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

步骤 4. 创建源内容

如果尚未创建，请创建一个或多个包含待翻译内容的 MDX 文件。这些文件的路径中必须包含源语言环境（例如，作为目录名称 en/ 或作为文件名的一部分 messages.en.mdx）。

步骤 5. 创建存储桶

在 i18n.json 文件中，向 buckets 对象添加一个 "mdx" 对象：

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

在 "mdx" 对象中，定义一个或多个 include 模式的数组：
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "mdx": {
      "include": ["./[locale]/example.mdx"]
    }
  }
}
```
这些模式定义了需要翻译的文件。

模式本身：
- 必须包含 [locale] 作为配置语言环境的占位符
- 可以指向文件路径（例如，"[locale]/blog.mdx"）
- 可以使用星号作为通配符占位符（例如，"[locale]/*.mdx"）
不支持递归的 glob 模式（例如，**/*.mdx）。

第 6 步：配置 LLM

Lingo.dev CLI 使用大型语言模型 (LLM) 通过 AI 翻译内容。要使用这些模型之一，您需要从支持的提供商处获取 API 密钥。

为了尽快开始使用，我们推荐使用 Lingo.dev Engine —— 我们自己的托管平台，每月提供 10,000 个免费令牌的使用额度：

注册一个 Lingo.dev 账户。
运行以下命令：
```
npx lingo.dev@latest login
```
这将打开您的默认浏览器并要求您进行身份验证。
按照提示操作。

第 7 步：生成翻译

在包含 i18n.json 文件的目录中，运行以下命令：

npx lingo.dev@latest run

此命令将：

读取 i18n.json 文件。
查找需要翻译的文件。
从文件中提取可翻译的内容。
使用配置的 LLM 翻译提取的内容。
将翻译后的内容写回文件系统。

首次生成翻译时，会创建一个 i18n.lock 文件。此文件记录已翻译的内容，防止在后续运行中进行不必要的重新翻译。

示例

en/example.mdx


---

title: "餐厅评论：Bella Vista"
description: "我们在市中心新开的意大利餐厅的用餐体验"
author: "not-localized-author"
published: "2024-03-15"
rating: 4.5
locked_key_1: "此值在所有语言环境中应保持不变"
ignored_key_1: "此字段不应出现在目标语言环境中"

---

# Bella Vista 晚餐

我们终于尝试了上个月在主街新开的意大利餐厅。以下是我们的真实评论。

## 氛围

这家餐厅拥有温暖、令人愉悦的氛围，包括：

- **柔和的灯光**，营造出亲密的环境
- 背景中播放的*轻柔爵士音乐*
- 每张桌子上都有新鲜的花朵

es/example.mdx


---

title: "餐厅评论：Bella Vista"
description: "我们在市中心新开的意大利餐厅的用餐体验"
author: "not-localized-author"
published: "2024-03-15"
rating: 4.5
locked_key_1: "This value should remain unchanged in all locales"

---

# 在 Bella Vista 的晚餐

我们终于尝试了上个月在 Main Street 新开的意大利餐厅。这是我们诚实的评论。

## 氛围

这家餐厅拥有温暖、令人愉悦的氛围，包括：

- **柔和的灯光**，营造出亲密的环境
- 背景中播放的*轻柔爵士音乐*
- 每张桌子上都有新鲜的花朵

i18n.json

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

i18n.lock

version: 1
checksums:
  0d5b5aa6d2b9937d47fd63868ef9e9f6:
    meta/title: a4bdd0dee24f8318f3300dcae130a353
    meta/description: 609213841f122e494f62262618ee4761
    meta/author: f3f7164b5963b4da6cd31a2ec0251630
    content/0: 8a8520492d23503da5691602e60bd22a
    content/1: 1fc859854cda505b2a94a04c8b09ab43
    content/2: 8add667f2a1d5d791a64b50bde54fa59
    content/3: e6e34c4c92eda512ec209266abe8e074
    content/4: 07f1896ad050b9606d7674f70d847818
    content/5: bd4d40a4f0cc92ac8a880c8d9ce8b43d
    content/6: 3036a07a887121ea080427d84fc80912
    content/7: f555318416c5c5388c1d961ef02f5955
    content/8: 90e02688ab103de60e42c70ece7efc4d
    content/9: 8c5be3cd002a3a194c991821e0182e08
    content/10: 3495801a7461ac5ea8d78369873a5409
    content/11: d444739ce3d48afb7976067c67149a9e
    content/12: 5f02c0a3b6385f80bdd08cf7e2d8c04d
    content/13: 0a15fd446b87d907f58c303aece0882b
    content/14: 778ed0aa1f81768280a23afe559c55f7
    content/15: fa244af2d8e558d6c3644ff8c1a64562
    content/16: 14f593e7cf3b3df84a21e17db318912e
    content/17: 5f42d26a42aa29be063019eea27ad07c
    content/18: 48bb7e89e72d68d6de12f5cdac64fc18
    content/19: 1639b9ef57bf363e04293e27d1c13952
    content/20: bb1c8d22064f7af4879c69d444e6e769
    content/21: 52f9d6beaa85591f77811e1162d756c4