每语言一个 CSV 文件

使用 Lingo.dev CLI 对每个语言单独的 CSV 文件进行 AI 翻译

什么是每语言一个 CSV？

每语言一个 CSV 是一种翻译方式，每个语言都有独立的 CSV 文件，而不是将所有语言存储在一个包含多列的 CSV 文件中。这种格式适用于具有多列结构化数据（如产品目录、用户数据或内容管理系统）的场景，其中每一行代表一条记录，每一列代表不同的字段。

例如：

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3

与标准的 CSV bucket 不同，标准 bucket 会将所有语言存储在一个文件中，列如 KEY,en,es，而 csv-per-locale bucket 则为每个语言维护独立的文件，保留原始 CSV 的所有列结构。

什么是 Lingo.dev CLI？

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

了解更多，请参见 概述。

关于本指南

本指南介绍如何使用 csv-per-locale bucket 结合 Lingo.dev CLI 翻译 CSV 文件。

你将学到如何：

  • 从零创建项目
  • 配置每语言单独 CSV 文件的翻译流水线
  • 使用 AI 生成翻译
  • 使用锁定和忽略的 key

前置条件

要使用 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. 配置源语言区域

源语言区域 是指您的内容最初编写时所用的语言和地区。要配置源语言区域，请在 locale.source 属性中于 i18n.json 文件中进行设置：

{
  "$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. 创建源内容

如果尚未创建，请为您的源语言区域新建一个 CSV 文件。该文件应包含：

  • 包含列名的表头行
  • 一行或多行数据
  • 所需的任意列（不限于特定列名）

CSV 文件的路径中必须包含源语言区域（例如，作为目录名 en/，或作为文件名的一部分 data.en.csv）。

注意： 与标准 CSV bucket 不同，您无需包含 "KEY" 列或与源语言区域相同的列。csv-per-locale bucket 会将每一行视为一条记录，并在保留结构的同时翻译 CSV 中的所有文本内容。

步骤 5. 创建 bucket

  1. 在 i18n.json 文件中，将 "csv-per-locale" 对象添加到 buckets 对象中：

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

  2. 在 "csv-per-locale" 对象中，定义一个包含一个或多个 include 模式的数组：

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

    这些模式用于定义需要翻译的文件。

    模式本身：

    • 必须包含 [locale] 作为已配置语言区域的占位符
    • 可以指向文件路径（例如 "[locale]/data.csv"）
    • 可以使用星号作为通配符（例如 "[locale]/*.csv"）

    不支持递归 glob 模式（例如 **/*.csv）。

  3. 可选地，您可以配置 lockedKeys 和 ignoredKeys：

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}
    • lockedKeys：不应被翻译的键（第一列的列值，通常为 ID）
    • ignoredKeys：不应出现在目标语言文件中的键

步骤 6. 配置 LLM

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

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

  1. 注册 Lingo.dev 账号。

  2. 运行以下命令：

    npx lingo.dev@latest login

    这将打开您的默认浏览器，并要求您进行身份验证。

  3. 按照提示操作。

步骤 7. 生成翻译内容

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

npx lingo.dev@latest run

该命令：

  1. 读取 i18n.json 文件。
  2. 查找需要翻译的文件。
  3. 从 CSV 文件中提取可翻译内容。
  4. 使用已配置的 LLM 翻译提取的内容。
  5. 将翻译后的内容分别写入每个目标语言的 CSV 文件。

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

示例

en/example.csv（翻译前）

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3
4,Success,Operation completed successfully,2024-01-01,true,4
5,Loading,Please wait while we load your data,2024-01-01,true,5

es/example.csv（翻译后）

id,name,description,created,enabled,sort
1,Bienvenida,Bienvenido a nuestra aplicación,2024-01-01,true,1
2,Guardar,Guarda tus cambios,2024-01-01,true,2
3,Error,Ha ocurrido un error,2024-01-01,true,3
4,Éxito,Operación completada con éxito,2024-01-01,true,4
5,Cargando,Por favor espera mientras cargamos tus datos,2024-01-01,true,5

i18n.json

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

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    0/name: 1308168cca4fa5d8d7a0cf24e55e93fc
    0/description: 8de4bc8832b11b380bc4cbcedc16e48b
    1/name: f7a2929f33bc420195e59ac5a8bcd454
    1/description: 8de4bc8832b11b380bc4cbcedc16e48b
    2/name: d3d99b147cc363dc6db8a48e8a13d4c1
    2/description: 7cd986af1fe5e89abe7ecffba5413110

与 CSV bucket 的区别

csv-per-locale bucket 与标准 csv bucket 在多个方面有所不同：

  • 文件结构：csv-per-locale 为每个语言环境使用单独的文件（如 en/example.csv、es/example.csv），而 csv 使用包含多列的单一文件（如 KEY,en,es）。

  • 列要求：csv-per-locale 不需要 "KEY" 列或以语言环境命名的列。你可以根据数据需求自定义列结构。

  • 使用场景：csv-per-locale 适用于如产品目录、内容管理系统或数据库等结构化数据，每行代表一个包含多个字段的记录。标准 csv bucket 更适合简单的键值对翻译表。

  • 文件变更：两种 bucket 都会直接修改文件，但 csv-per-locale 会为每个语言环境创建单独的文件，而 csv 则是在现有文件中添加新列。