WebVTT 字幕

使用 Lingo.dev CLI 对 WebVTT 字幕文件进行 AI 翻译

什么是 WebVTT 字幕？

WebVTT（Web Video Text Tracks）字幕是一种用于在 HTML5 视频中显示定时文本轨道的格式。它支持样式、定位和元数据，比 SRT 格式功能更丰富。

例如：

WEBVTT

NOTE
Product demonstration video with captions

1
00:00:01.000 --> 00:00:03.500
Welcome to our software tutorial

subtitle-2
00:00:04.000 --> 00:00:07.200
Let's explore the main features

3
00:00:08.500 --> 00:00:12.000 align:middle line:90%
Here's how to create your first project

什么是 Lingo.dev CLI？

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

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

关于本指南

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

你将学习如何：

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

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

第 5 步：创建 bucket

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

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

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

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

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

    模式本身：

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

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

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

WEBVTT

NOTE
Product demonstration video with captions

1
00:00:01.000 --> 00:00:03.500
Welcome to our software tutorial

subtitle-2
00:00:04.000 --> 00:00:07.200
Let's explore the main features

3
00:00:08.500 --> 00:00:12.000 align:middle line:90%
Here's how to create your first project

00:00:13.000 --> 00:00:16.500
Click the New Project button
to get started

final-cue
00:00:17.000 --> 00:00:20.000 position:25% align:start
That completes our basic tutorial

es/example.vtt

WEBVTT

NOTE
Video de demostración de producto con subtítulos

1
00:00:01.000 --> 00:00:03.500
Bienvenido a nuestro tutorial de software

subtitle-2
00:00:04.000 --> 00:00:07.200
Exploremos las características principales

3
00:00:08.500 --> 00:00:12.000 align:middle line:90%
Aquí está cómo crear tu primer proyecto

00:00:13.000 --> 00:00:16.500
Haz clic en el botón Nuevo Proyecto
para comenzar

final-cue
00:00:17.000 --> 00:00:20.000 position:25% align:start
Eso completa nuestro tutorial básico

i18n.json

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

i18n.lock

version: 1
checksums:
  ab6437a18c50af6612bb75499361d64a:
    0#1-3.5#1: 5df3c06b74cfc8558e85ff75a30a9162
    1#4-7.2#subtitle-2: 0de65f1d2616b6959aa79ac5beb6e84c
    2#8.5-12#3: 3351244c032529a099f1191477d9e488
    3#13-16.5#: b9341abc965d5178a96d9bc4e8e2c59a
    4#17-20#final-cue: 0b67e089cd3f39b8520d7a2be9f34362