HTML - Lingo.dev CLI

什么是 HTML？

HTML（超文本标记语言，HyperText Markup Language）是用于创建网页和 Web 应用的标准标记语言。它通过标签来结构化内容，并定义诸如标题、段落、链接、图片和表单等元素。

什么是 Lingo.dev CLI？

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

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

关于本指南

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

你将学习如何：

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

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

对于 HTML 文件，可翻译内容包括：

HTML 元素内的文本内容
属性值，包括：
- alt 属性（图片描述）
- title 属性（工具提示）
- placeholder 属性（输入提示）
- value 属性（按钮和输入值）
- meta 标签的 content 属性
lang 属性会自动更新为目标语言区域

script 标签、style 标签和不可翻译的属性会被保留。

例如：

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyApp - Hello World</title>
    <meta name="description" content="A simple demo app" />
  </head>
  <body>
    <h1>Welcome to MyApp</h1>
    <p>Hello, world! This is a simple demo with <strong>bold text</strong>.</p>
    <img src="example.jpg" alt="Example image" />
  </body>
</html>

步骤 5. 创建 bucket

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

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

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

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

步骤 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.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyApp - Hello World</title>
    <meta name="description" content="A simple demo app" />
  </head>
  <body>
    <h1>Welcome to MyApp</h1>
    <p>Hello, world! This is a simple demo with <strong>bold text</strong>.</p>
    <img src="example.jpg" alt="Example image" />
    <input type="text" placeholder="Enter text here" />
    <a href="#" title="Click for more">Learn more</a>
  </body>
</html>

es/example.html

<!DOCTYPE html>
<html lang="es">
  <head>
    <title>MyApp - Hola Mundo</title>
    <meta name="description" content="Una aplicación de demostración simple" />
  </head>
  <body>
    <h1>Bienvenido a MyApp</h1>
    <p>¡Hola, mundo! Esta es una demostración simple con <strong>texto en negrita</strong>.</p>
    <img src="example.jpg" alt="Imagen de ejemplo" />
    <input type="text" placeholder="Ingresa texto aquí" />
    <a href="#" title="Haz clic para más">Saber más</a>
  </body>
</html>

i18n.json

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

i18n.lock

version: 1
checksums:
  ab95e8c959a889717f02a05af5c5b1e6:
    head/0/0: 7d39787547365ee4194f29f3f54e5c05
    head/1#content: 49f8864eb0e53903f04532bf33e1e4fa
    head/2#content: c2a1da93efb7e744d100df705e5fcbfd
    head/3#content: d94b318cb327f61f1aea44a6cb1fdcad
    body/0/0: d1c3a9f35e377554a4ccaa467ca26614
    body/1/0: e19afd1952881bdf10063f9478980147
    body/1/1/0: 7cd9256312384858ecba6c29d3c2e550
    body/1/2: ce8b9bb44f031705708a70e068bb73c8
    body/1/3/0: 037d114f19b882f08994712b8d9c1e37
    body/1/4: f05f450fffcb17520c441ab9789f40ce
    body/2/0/0/0: 57d373bcffe2d376cbf9919da30ca30b
    body/3#alt: 68f95fca639f8bf72a4796b6734b02d5
    body/4#alt: cb7d920c3bbcade1c8e0307093f58573
    body/5#placeholder: a05ce3b4578f55e41bd2ad4964f966b4
    body/6#placeholder: a4554ed67c02872e302b0042724f859d
    body/7#title: c903c6985a40ce02d65c90229de35a4e
    body/7/0: e598091d132f890c37a6d4ed94f6d794
    body/8#title: d656021ba5f485fa1a82f8aac6ecc5de
    body/8/0: 1c6856488bd34ad87fcacce2d8e66a0b
    body/9/0: 862964e6cd73cdffdcac622406c6bac9