JSON 词典 - Lingo.dev CLI

什么是 JSON 词典？

JSON 词典是一种本地化格式，用于在单个 JSON 文件中存储多个语言环境的所有翻译。每个键包含一个以语言环境代码为键、翻译字符串为值的对象，便于集中管理所有翻译内容。

例如：

{
  "navigation": {
    "en": "Home"
  },
  "buttons": {
    "submit": {
      "en": "Submit"
    },
    "cancel": {
      "en": "Cancel"
    }
  },
  "forms": {
    "login": {
      "username": {
        "en": "Username"
      }
    }
  }
}

什么是 Lingo.dev CLI？

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

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

关于本指南

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

你将学到如何：

从零创建项目
配置翻译流水线
使用 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 步：创建源内容

如果尚未创建，请新建一个包含待翻译内容的 JSON 字典文件。

注意： 在翻译过程中，源内容文件将被覆盖，包含翻译后的内容（以及源内容）。

第 5 步：创建 bucket

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

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

在 "json-dictionary" 对象中，定义一个或多个 include 模式的数组：
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "json-dictionary": {
      "include": ["./example.json"]
    }
  }
}
```
这些模式用于定义需要翻译的文件，可以：
- 指定具体的文件路径（如 "some/dir/file.json"）
- 使用星号作为通配符（如 "some/dir/*.json"）
不支持递归 glob 模式（如 **/*.json）。

第 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 文件。该文件用于记录已翻译的内容，防止后续运行时重复翻译。

示例

example.json（翻译前）

{
  "navigation": {
    "en": "Home"
  },
  "buttons": {
    "submit": {
      "en": "Submit"
    },
    "cancel": {
      "en": "Cancel"
    }
  },
  "messages": {
    "welcome": {
      "en": "Welcome to our application"
    },
    "error": {
      "en": "An error occurred"
    }
  },
  "forms": {
    "login": {
      "title": {
        "en": "Login"
      },
      "fields": {
        "username": {
          "en": "Username"
        },
        "password": {
          "en": "Password"
        }
      }
    }
  }
}

example.json（翻译后）

{
  "navigation": {
    "en": "Home",
    "es": "Inicio"
  },
  "buttons": {
    "submit": {
      "en": "Submit",
      "es": "Enviar"
    },
    "cancel": {
      "en": "Cancel",
      "es": "Cancelar"
    }
  },
  "messages": {
    "welcome": {
      "en": "Welcome to our application",
      "es": "Bienvenido a nuestra aplicación"
    },
    "error": {
      "en": "An error occurred",
      "es": "Ha ocurrido un error"
    }
  },
  "forms": {
    "login": {
      "title": {
        "en": "Login",
        "es": "Iniciar sesión"
      },
      "fields": {
        "username": {
          "en": "Username",
          "es": "Nombre de usuario"
        },
        "password": {
          "en": "Password",
          "es": "Contraseña"
        }
      }
    }
  }
}

i18n.json

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

i18n.lock

version: 1
checksums:
  455da9346f4e772000927cd2ff5bb898:
    navigation: 104a3db3b671c04e167eafbe21e57881
    buttons/submit: 7c91ef5f747eea9f77a9c4f23e19fb2e
    buttons/cancel: 2e2a849c2223911717de8caa2c71bade
    messages/welcome: 1308168cca4fa5d8d7a0cf24e55e93fc
    messages/error: 53a2b5f5e7d83c737c8e02fe18fb4bdb
    forms/login/title: f4f219abeb5a465ecb1c7efaf50246de
    forms/login/fields/username: 2ee65bc2dd2f12cf2672f95b2a054bf8
    forms/login/fields/password: 223a61cf906ab9c40d22612c588dff48
  a8f80a1a4e0e0aa2750e514a8a6abacf:
    navigation: 104a3db3b671c04e167eafbe21e57881
    buttons/submit: 7c91ef5f747eea9f77a9c4f23e19fb2e
    buttons/cancel: 2e2a849c2223911717de8caa2c71bade
    messages/welcome: 1308168cca4fa5d8d7a0cf24e55e93fc
    messages/error: 53a2b5f5e7d83c737c8e02fe18fb4bdb
    forms/login/title: f4f219abeb5a465ecb1c7efaf50246de
    forms/login/fields/username: 2ee65bc2dd2f12cf2672f95b2a054bf8
    forms/login/fields/password: 223a61cf906ab9c40d22612c588dff48