纯文本

使用 Lingo.dev CLI 对纯文本文件进行 AI 翻译

什么是纯文本？

纯文本文件（.txt）是仅包含可读字符的简单、无格式文本文件。它们通常用于文档、笔记以及不需要结构化格式的简单内容。

例如：

This is the first line of text content
This is the second line with different content
This line contains special characters: !@#$%^&*()

Thank you for choosing our service

什么是 Lingo.dev CLI？

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

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

关于本指南

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

你将学到如何：

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

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

第 5 步：创建 bucket

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

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

  2. 在 "txt" 对象中，定义一个或多个 include 模式的数组：

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

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

    模式要求如下：

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

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

第 6 步：配置 LLM

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

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

  1. 注册 Lingo.dev 账号。

  2. 运行以下命令：

    npx lingo.dev@latest login

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

  1. 按照提示操作。

步骤 7. 生成翻译内容

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

npx lingo.dev@latest run

该命令将：

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

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

示例

en/example.txt

This is the first line of text content
This is the second line with different content
This line contains special characters: !@#$%^&*()

This is line five after an empty line above
Thank you for choosing our service

es/example.txt

Esta es la primera línea de contenido de texto
Esta es la segunda línea con contenido diferente
Esta línea contiene caracteres especiales: !@#$%^&*()

Esta es la línea cinco después de una línea vacía arriba
Gracias por elegir nuestro servicio

i18n.json

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

i18n.lock

version: 1
checksums:
  93e6c54f553af59fa33d7469c80a30e9:
    "1": 5c0212aca9c84332df0190d13e929623
    "2": d39d54116929959bf76f43655e7bebc9
    "3": 960c83d6eeed679ee9fb1b2be2f9934b
    "5": 78569dd2f0e7cd872659850ef2f9c19a
    "6": 5c5a850ec695512b6182630c563eeed9