快速入门

快速上手 Lingo.dev CLI

Lingo.dev CLI 的核心优势在于通过单个 CLI 命令高效地将应用程序和 Markdown 内容本地化为目标语言。

本快速入门指南假设您即将使您的应用程序支持多语言，或者已经配置了支持两种或更多语言的功能。因此，本指南设计得足够简短，可以在 10 分钟内完成，但又足够详细以便理解其内部工作原理。

完成本指南后，您将能够：

  1. 使用 AI 翻译引擎将应用内容本地化为西班牙语和日语；
  2. 理解源文件、目标文件和配置如何协同工作；
  3. 设置一个本地化工作流，使您的应用程序和 Markdown 内容能够扩展到数十种语言和数万字。

让我们开始吧！

前置条件

Markdown

Markdown 文件是结构化文档，这意味着无需进行任何预先设置。Lingo.dev CLI 可以直接处理 .md 文件，在本地化内容的同时保持格式，因此您可以直接进入 步骤 1。

应用程序

要使应用程序支持多语言，现代 Web 和移动应用程序需要开发人员首先设置国际化 (i18n) 配置。

在本快速入门中，我们将创建一个独立的 JSON 文件，演示 Lingo.dev CLI 如何本地化应用程序内容。

在与您的实际应用程序集成时，请参考我们推荐的框架指南：

仅适用于 Windows：通过 npx 运行

如果您是第一次运行 npx，它需要 Bash 或其他兼容的 shell。在 Windows 上，您可以安装 Git for Windows。

安装后，在第一次运行 npx 之前，通过在终端中运行以下命令之一（取决于 Git Bash 的安装位置）来设置 npx 的 shell：

npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"

或

npm config set script-shell "C:\\Program Files (x86)\\git\\bin\\bash.exe"

这是在 Windows 上正确执行 lingo.dev 包所必需的。

第 1 步：初始化项目

Lingo.dev CLI 使用标准的 i18n.json 配置文件来声明您的本地化设置。要以交互方式创建它，请运行：

npx lingo.dev@latest init

它会询问您有关项目的问题，然后在项目根目录中创建一个 i18n.json 文件。

该文件应如下所示：

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

让我们逐一解析每个配置元素：

  • locale.source — 您的团队编写内容所使用的语言。此设置标识哪些文件包含权威内容。所有本地化流程都从源语言流向目标语言。

  • locale.targets — 一个 ISO 639-1 语言代码数组，表示您的目标市场。每个代码对应一个单独的文件（或文件中的一个部分，具体取决于格式）。您可以从一两种语言开始，并在扩展时添加更多语言。

  • buckets.json.include — 类似于 glob 的模式，用于告诉 CLI 在哪里查找和创建语言文件。特殊的 [locale] 标记会扩展为每个语言代码。使用模式 locales/[locale].json，CLI 会查找 locales/en.json 作为源文件，并生成 locales/es.json 和 locales/ja.json 作为目标文件。您可以指定多个模式，甚至在单个配置中混合使用多种格式。

随着项目的增长，您会发现更多高级功能：

  • 针对不同文件类型或应用程序部分的多个存储桶
  • 跳过某些文件的 exclude 模式
  • 防止特定值被翻译的 lockedKeys

创建英文源文件

在本快速入门中，我们将创建一个语言环境文件：

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

这将创建一个 locales 目录和一个包含两个翻译键的英文源文件。像 greeting 这样的键适用于扁平结构，而像 button.submit 这样的命名空间键有助于组织更大的应用程序。

嵌套对象也受支持。您可以在其余文档中找到有关不同文件格式的更多详细信息。

第 2 步. 身份验证

Lingo.dev CLI 将您的内容发送到 AI 翻译引擎进行本地化，因此我们需要先进行身份验证。

选项 1. 原始 LLM API 访问

Lingo.dev CLI 帮助您使用 LLM 模型（如 OpenAI 或 Anthropic）进行本地化和翻译。

这意味着您按处理的 token 计费，您可以控制模型选择、系统提示和所有模型参数。

要进行身份验证，请在项目根目录中创建一个 .env 文件并添加您的 API 密钥：