JSONC - Lingo.dev CLI

什么是 JSONC？

JSONC（带注释的 JSON）是 JSON 的一种扩展，允许使用单行和多行注释。它通常用于需要人类可读注释的配置文件中。

例如：

{
  "key1": "你好，世界！", // 这是 key1 的注释
  "key2": "一个带有 JSONC 功能的简单演示应用" /* 这是 key2 的注释 */,
  // 这是 key3 的注释
  "key3": "1.0.0",
  // 这是嵌套值的注释
  "key6": {
    "key7": "嵌套值",
  },
  // 此键已锁定，不应更改
  "locked_key_1": "此值已锁定，不应更改",
}

什么是 Lingo.dev CLI？

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

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

关于本指南

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

您将学习如何：

从头开始创建项目
配置翻译流水线
使用 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. 创建源内容

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

步骤 5. 创建存储桶

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

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

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

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

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

{
  "key1": "你好，世界！", // 这是 key1 的注释
  "key2": "一个带有 JSONC 功能的简单演示应用" /* 这是 key2 的注释 */,
  // 这是 key3 的注释
  "key3": "1.0.0",
  /* 这是 key4 的块注释 */
  "key4": "[email protected]",
  /*
   这是 key5 的注释
  */
  "key5": "🚀",
  // 这是 key6 的注释
  "key6": {
    // 这是 key7 的注释
    "key7": "嵌套值",
  },
  // 此键已锁定，不应更改
  "locked_key_1": "此值已锁定，不应更改",
  // 此键被忽略，不应出现在目标语言环境中
  "ignored_key_1": "此值被忽略，不应出现在目标语言环境中",
}

es/example.jsonc

{
  "key1": "¡Hola, mundo!", // 这是 key1 的注释
  "key2": "一个带有 JSONC 特性的简单演示应用" /* 这是 key2 的注释 */,
  // 这是 key3 的注释
  "key3": "1.0.0",
  /* 这是 key4 的块注释 */
  "key4": "[email protected]",
  /*
   这是 key5 的注释
  */
  "key5": "🚀",
  // 这是 key6 的注释
  "key6": {
    // 这是 key7 的注释
    "key7": "嵌套值",
  },
  // 此键已锁定，不应更改
  "locked_key_1": "此值已锁定，不应更改",
}

i18n.json

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

i18n.lock

version: 1
checksums:
  455da9346f4e772000927cd2ff5bb898:
    title: 0468579ef2fbc83c9d520c2f2f1c5059
    description: 6f4922f45568161a8cdf4ad2299f6d23
    version: 54a9e730e88fb16291b852274d433923
    support_email: 10627fcc465897af0f5e1bba042685f9
    emoji: b328c432cee108a87a92f05258b6a651
    author/name: febee8e9ab40b2fe5106d72675228d00
    contributors/0/name: e80d4063a32adaad7b0a82b0bcc10551
    contributors/1/name: b2bca2fa3c890618e56d07473f26ead3
    messages/0: d1c3a9f35e377554a4ccaa467ca26614
    messages/1: 0468579ef2fbc83c9d520c2f2f1c5059
    config/theme/primary: 7535a3779d6934ea8ecf18f5cb5b93fd
    mixed_array/0: 001b5b003d96c133534f5907abffdf77
    mixed_array/3/nested_message: 5f0782dfc5993e99890c0475bc295a30