Markdoc - Lingo.dev CLI

什么是 Markdoc？

Markdoc 是一种基于 Markdown 的语法和工具链，用于创建自定义文档站点。它通过自定义标签、变量和属性扩展了 Markdown，以创建丰富的交互式内容。

例如：


---

title: Markdoc 简介
description: Markdoc 功能和语法的全面演示

---

# Markdoc 简介

欢迎阅读这份 **Markdoc 演示** 文档。

{% callout type="note" %}
这是一个展示 Markdoc 功能的示例文档。
{% /callout %}

## 基本格式

- 普通文本
- *斜体文本*
- **加粗文本**

什么是 Lingo.dev CLI？

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

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

关于本指南

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

您将学习如何：

从头开始创建项目
配置翻译管道
使用 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 步：创建源内容

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

第 5 步：创建存储桶

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

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

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

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

第 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.markdoc


---

title: Markdoc 简介
description: Markdoc 功能和语法的全面演示
author: 文档团队
version: 1.0

---

# Markdoc 简介

欢迎阅读这份 **Markdoc 演示** 文档。此文件展示了 Markdoc 的各种功能和语法。

{% callout type="note" %}
这是一个展示 Markdoc 功能的示例文档。
{% /callout %}

## 基本格式

Markdoc 支持标准的 Markdown 功能：

1. 有序列表
2. 无序列表
3. 文本格式，如 *斜体* 和 **加粗**

es/example.markdoc


---

title: Markdoc 简介
description: Markdoc 功能和语法的全面演示
author: 文档团队
version: 1.0

---

# Markdoc 简介

欢迎阅读这份 **Markdoc 演示** 文档。此文件展示了 Markdoc 的各种功能和语法。

{% callout type="note" %}
这是一个展示 Markdoc 功能的示例文档。
{% /callout %}

## 基本格式

Markdoc 支持标准的 Markdown 功能：

1. 有序列表
2. 无序列表
3. 文本格式，如 *斜体* 和 **加粗**

i18n.json

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

i18n.lock

version: 1
checksums:
  829674e11a9003549b66978e9b9c259a:
    heading-0: e19079d431e6b75a7d74e9c35639ea5a
    paragraph-0: 6757b797fc6d8c5ec5628f2619274e28
    paragraph-1: cc37b30c1aca11f64dc096264761368e
    paragraph-2: 50e2b92b9e711ae7758f8edcc1767102
    paragraph-3: 7bc573b304cf3a3414dd60f85eea4e36
    heading-1: 80779abd23399c676227609057093235
    paragraph-4: dfd87f4dde3d3e12fa6781966432465f
    item-0: ad9b7460be42c194e4771cf5281d5fd0
    item-1: 7d67473952061a571de034013964c5b6
    item-2: 91cffca4db2b901a3a0310ca2ab17ed9
    item-3: 56b97b82cc030c511847d1850af088a0
    item-4: 05dc0a811ee5b04941c826293471367d
    item-5: b1701133f7e62467e354a5fc526ea951
    heading-2: ff6e4ea57280ef5a42ebbe2cf9e3273b
    paragraph-5: 3e11ad608af106c15eed82d0e5d07712
    item-6: 2b1ab56131399aab1842fc3a81dd170e
    item-7: 8aedf70e351d5e5bb41ad66ad5ad18d8
    item-8: 1d0eccad0413a69da0d45c481aa754e9
    paragraph-6: e2a208aa62fd61821848519fa2abc211
    heading-3: 2761eb3f80a7da53d2cd899f33641e98
    paragraph-7: f341db1f3167bd074937f4399c3a1158
    th-0: 58f5f3f37862b6312a2f20ec1a1fd0e8
    th-1: e17686a22ffad04cc7bb70524ed4478b
    td-0: 97813c8ae67d69575fd04e35a88aed0c
    td-1: 117451569b718867c43b26d9ee3c4e8f
    td-2: e801c1eaca53c3aa702b747ed750fdd1
    td-3: ffd3eec5497af36d7b4e4185bad1313a
    td-4: 03d20ebc4966301ceba02199a24e02dc
    td-5: 86d0ae6fea0fbb119722ed3841f8385a
    td-6: 6d26991f040628f6002efa192bebb9c2
    heading-4: c8b45e4d54115ec279a2a6bde4b8a725
    paragraph-8: 933c68ed0598328263d1146641d0ab2c
    fence-0: ffdb698812040ead47e2039dfa22d9d7
    paragraph-9: fe471cd364c38cc79a7638b4a5ffb528
    heading-5: 4cbc75f1ae6830a190eb70628c4e4b54
    paragraph-10: bc6097c6af86133a3972bdb7a5343dd2
    fence-1: 31a1aab989ce9935c98e672182bffbbe
    heading-6: fe53e9de958685ab7c70d0a973c0a146
    paragraph-11: 69f77475eb830f1aa357f45db29f809e
    item-9: 90f2650aad06503472c46ce2612b9bc8
    item-10: a392737d0507463d40d1a8ff7502607c
    item-11: 7ed6e23ffae34636a417daf72b3a5b6b
    item-12: 0f93e7285aafb5c9929b29973f047026
    item-13: 9dacb7c56bc894e4bcad39f41265e3a0
    item-14: 496e1d7de5d7ff53f1af813a2ba46d7f
    item-15: 1bd4ec30282cfc0bdf7d5f3559990a1c
    item-16: 46c9eec1392a8d9f33170569e342bf7b
    heading-7: aa8d69ad456402762aeb915a67cfa698
    paragraph-12: 275eb44389d498dab93e38ed2889e5d9
    paragraph-13: f05f450fffcb17520c441ab9789f40ce
    paragraph-14: 915fe5ce4ded772d7844df222ebd9d3e
    paragraph-15: 3fae115ccac303b7cd908b49b8509217
    heading-8: 2fdf7c243436eba4bd1fe5ebd605ab96
    paragraph-16: fc0f77d45ad1e1764d2793706eb8a049
    paragraph-17: 6b4340d30988a714d34f0df9b3e18889
    paragraph-18: a59d117938ed65f303209da2b23ad35a
    paragraph-19: 28e8b27fb60b305a9caac04d8a92a038
    tagName-0: 0421db688c4d19bb542014733d553a43
    paragraph-20: 83951ea4c30a9b5057ff046e3a0bfc07
    paragraph-21: 8d2152d9e84fff4b3cd98d1fb305be8f
    heading-9: 6fe6489310962f6bc8ad13279106568b
    item-17: 0539fa4e65545d8a334abf6e0aee57ab
    item-18: a41ccc6f28eec377fb19a95b0b6db7a8
    item-19: 45aa24cef8a5d9b037d898917a862563
    paragraph-22: 59bf7b09d603b846c2cdd63cd878f20a
    paragraph-23: 9e30a94d9122095ac52a52ed2a864a26
    paragraph-24: 3b28910e425d79f9fd23ada6d6f33bff
    paragraph-25: 05d9c0fe6c099b1e20ebdb2320a28257
    paragraph-26: 04e7322f2d3ffb2d73ff2f64b71637c8
    paragraph-27: 65ef9814c2d07fd3d54d9f7bee1bba6c
    badge-0: c2d5d8760d96802e1b9a7bac290b1cfc
    paragraph-28: df1f854bcdb047d98a68cd39704a8981
    fm-attr-title: e19079d431e6b75a7d74e9c35639ea5a
    fm-attr-description: 82574f93a40b35a16a4c9fc5c2ab58cf
    fm-attr-author: a51ec27845d1fc7cf13c810f0e2d42ab