JSON5 - Lingo.dev CLI

什么是 JSON5？

JSON5 是对 JSON 的扩展，使人们更容易手动编写和维护。它支持注释、非引号键、尾随逗号以及更灵活的语法，同时与 JavaScript 保持兼容。

例如：

{
  // JSON5 allows comments!
  title: "Hello, world!",
  description: "A simple demo app with JSON5 features",

  // Unquoted keys are allowed
  author: {
    name: "John Doe",
  },

  messages: ["Welcome to MyApp", "Hello, world!"],

  // Trailing commas are allowed
  locked_key_1: "This value is locked and should not be changed",
}

什么是 Lingo.dev CLI？

Lingo.dev CLI 是一个免费的开源命令行工具，可通过 AI 翻译应用和内容。它旨在替代传统的翻译管理软件，并可集成到现有的开发流水线中。

如需了解更多信息，请参阅概览。

关于本指南

本指南介绍如何使用 Lingo.dev CLI 翻译 JSON5 文件。

你将学到如何：

从零创建项目
配置翻译流水线
使用 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 步：配置目标语言区域

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

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

第 4 步：创建源内容

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

第 5 步：创建 bucket

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

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

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

模式要求如下：
- 必须包含 [locale] 作为已配置语言区域的占位符
- 可以指向文件路径（如 "[locale]/config.json5"）
- 可以使用星号作为通配符（如 "[locale]/*.json5"）
不支持递归 glob 模式（如 **/*.json5）。

第 6 步：配置 LLM

Lingo.dev CLI 使用大型语言模型（LLM）通过 AI 翻译内容。要使用这些模型，您需要从支持的服务商获取 API 密钥。

为了尽快开始使用，我们推荐使用 Lingo.dev Engine —— 我们自有的托管平台，每月可免费使用 10,000 个 token：

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

步骤 7. 生成翻译内容

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

npx lingo.dev@latest run

该命令将：

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

首次生成翻译时，会创建一个 i18n.lock 文件。该文件用于记录已翻译的内容，防止后续运行时重复翻译。

示例

en/example.json5

{
  // JSON5 allows comments!
  title: "Hello, world!",
  description: "A simple demo app with JSON5 features",
  version: "1.0.0",
  support_email: "[email protected]",
  homepage: "https://lingo.dev",
  deprecated: null,
  empty: "",
  emoji: "🚀",

  // Unquoted keys are allowed
  author: {
    name: "John Doe",
  },

  contributors: [{ name: "Alice" }, { name: "Bob" }],

  messages: ["Welcome to MyApp", "Hello, world!"],

  config: {
    theme: {
      primary: "Blue theme",
    },
  },

  mixed_array: [
    "Mixed content here",
    42,
    true,
    {
      nested_message: "Nested text",
    },
  ],

  // Hexadecimal numbers work in JSON5
  hex_value: 0xdeadbeef,

  // Trailing commas are allowed
  locked_key_1: "This value is locked and should not be changed",
}

es/example.json5

{
  // JSON5 allows comments!
  title: "¡Hola, mundo!",
  description: "Una aplicación de demostración simple con características JSON5",
  version: "1.0.0",
  support_email: "[email protected]",
  homepage: "https://lingo.dev",
  deprecated: null,
  empty: "",
  emoji: "🚀",

  // Unquoted keys are allowed
  author: {
    name: "Juan Pérez",
  },

  contributors: [{ name: "Alicia" }, { name: "Roberto" }],

  messages: ["Bienvenido a MyApp", "¡Hola, mundo!"],

  config: {
    theme: {
      primary: "Tema azul",
    },
  },

  mixed_array: [
    "Contenido mixto aquí",
    42,
    true,
    {
      nested_message: "Texto anidado",
    },
  ],

  // Hexadecimal numbers work in JSON5
  hex_value: 0xdeadbeef,

  // Trailing commas are allowed
  locked_key_1: "This value is locked and should not be changed",
}

i18n.json

{
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "json5": {
      "include": ["./[locale]/example.json5"],
      "lockedKeys": ["locked_key_1"]
    }
  },
  "$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
    hex_value: a1b2c3d4e5f6789012345678abcdef01