CSV - Lingo.dev CLI

什么是 CSV？

CSV（逗号分隔值）是一种存储表格数据的纯文本文件格式，其中每一行代表一行数据，每行中的值由逗号分隔。

例如：

KEY,en
welcome_message,Welcome to our application
button_save,Save
error_invalid_email,Please enter a valid email address

什么是 Lingo.dev CLI？

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

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

关于本指南

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

您将学习如何：

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

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

对于 CSV 文件，需满足以下要求：

第一列必须命名为 "KEY"。
"KEY" 列中的每一行必须指定翻译消息的唯一 ID。
第二列必须与 i18n.json 文件中定义的源语言环境相同。
第二列中的每一行必须包含将被翻译的内容。

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

第 5 步：创建存储桶

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

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

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

第 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 文件。此文件会跟踪已翻译的内容，防止在后续运行中进行不必要的重新翻译。

示例

example.csv（翻译前）

KEY,en
welcome_message,Welcome to our application
button_save,Save
error_invalid_email,Please enter a valid email address
product_name,Premium Widget
empty_row_key,
whitespace_only,
new_feature,This is a new feature

example.csv（翻译后）

KEY,en,zh
welcome_message,Welcome to our application,欢迎使用我们的应用程序
button_save,Save,保存
error_invalid_email,Please enter a valid email address,请输入有效的电子邮件地址
product_name,Premium Widget,高级小部件
empty_row_key,,
whitespace_only,   ,
new_feature,This is a new feature,这是一个新功能

i18n.json

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

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    welcome_message: 1308168cca4fa5d8d7a0cf24e55e93fc
    button_save: f7a2929f33bc420195e59ac5a8bcd454
    error_invalid_email: 8de4bc8832b11b380bc4cbcedc16e48b
    product_name: d3d99b147cc363dc6db8a48e8a13d4c1
    new_feature: 7cd986af1fe5e89abe7ecffba5413110
  d0f33bd41270762260010c4723a564f5:
    welcome_message: 1308168cca4fa5d8d7a0cf24e55e93fc
    button_save: f7a2929f33bc420195e59ac5a8bcd454
    error_invalid_email: 8de4bc8832b11b380bc4cbcedc16e48b
    product_name: d3d99b147cc363dc6db8a48e8a13d4c1
    new_feature: 7cd986af1fe5e89abe7ecffba5413110