Properties 文件 - Lingo.dev CLI

什么是 Properties 文件？

Properties 文件是 Java 应用程序中常用的简单键值对文本文件，用于配置和本地化。

例如：

app.title=MyApp
app.description=A simple demo application

user.greeting=Hello, world!
user.farewell=Thanks for using MyApp

error.message=Something went wrong
error.notFound=Page not found

什么是 Lingo.dev CLI？

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

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

关于本指南

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

你将学习如何：

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

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

第 5 步：创建 bucket

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

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

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

模式本身：
- 必须包含 [locale] 作为已配置语言环境的占位符
- 可以指向文件路径（如 "[locale]/messages.properties"）
- 可以使用星号作为通配符（如 "[locale]/*.properties"）
不支持递归 glob 模式（如 **/*.properties）。

第 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.properties

app.title=MyApp
app.description=A simple demo application

user.greeting=Hello, world!
user.farewell=Thanks for using MyApp

error.message=Something went wrong
error.notFound=Page not found

database.host=localhost
database.port=5432

notification.success=Changes saved!
notification.warning=Please check your input

es/example.properties

app.title=MyApp
app.description=Una aplicación de demostración simple

user.greeting=¡Hola, mundo!
user.farewell=Gracias por usar MyApp

error.message=Algo salió mal
error.notFound=Página no encontrada

database.host=localhost
database.port=5432

notification.success=¡Cambios guardados!
notification.warning=Por favor verifica tu entrada

i18n.json

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

i18n.lock

version: 1
checksums:
  2250baa513dddb2c691cb62115d5e257:
    app.title: 7dc70110429d46e3685f385bd2cc941c
    app.description: e13baa1e885129d9328e216ff534761b
    user.greeting: 0468579ef2fbc83c9d520c2f2f1c5059
    user.farewell: 118794a2b84f7bfb4b4ce602ed463b0f
    error.message: a3cd2f01c073f1f5ff436d4b132d39cf
    error.notFound: 97612e6230bc7a1ebd99380bf561b732
    database.host: da86e4fc0c04d82c87006dc71cea7e97
    notification.success: 3b7a8b0aa23977592d4270ea136a390c
    notification.warning: c38895f731311cefacee9e8d7d10fc49