Flutter ARB - Lingo.dev CLI

什么是 Flutter ARB？

Flutter ARB（Application Resource Bundle）是一种基于 JSON 的格式，由 Google 的 Flutter 框架用于管理本地化字符串。它支持元数据、占位符和 ICU 消息格式，用于构建本地编译的应用程序。

什么是 Lingo.dev CLI？

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

要了解更多，请参阅概述。

关于本指南

本指南解释了如何使用 Lingo.dev CLI 翻译 Flutter ARB 文件。

您将学习如何：

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

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

对于 Flutter ARB 文件，需满足以下要求：

每个消息键必须有对应的翻译值
元数据条目（以 @ 开头）会被保留但不会被翻译
@@locale 元数据字段标识语言环境
占位符（{name}）在翻译过程中会被保留
支持用于复数和选择的 ICU 消息格式

例如：

{
  "@@locale": "en",
  "welcome_message": "欢迎使用我们的 Flutter 应用",
  "@welcome_message": {
    "description": "主屏幕上显示的欢迎消息"
  },
  "login_button": "登录",
  "greeting_with_name": "你好 {name}！",
  "@greeting_with_name": {
    "placeholders": {
      "name": {
        "type": "String"
      }
    }
  }
}

第 5 步：创建存储桶

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

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

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

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

第 6 步：配置 LLM

Lingo.dev CLI 使用大型语言模型 (LLMs) 通过 AI 翻译内容。要使用这些模型之一，您需要从支持的提供商处获取 API 密钥。

为了尽快开始使用，我们推荐使用 Lingo.dev Engine —— 我们自己的托管平台，每月提供 10,000 个免费令牌的使用额度：

注册一个 Lingo.dev 账户。
运行以下命令：
```
npx lingo.dev@latest login
```
这将打开您的默认浏览器并要求您进行身份验证。
按照提示操作。

第 7 步：生成翻译

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

npx lingo.dev@latest run

此命令将：

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

首次生成翻译时，会创建一个 i18n.lock 文件。此文件会跟踪已翻译的内容，防止在后续运行中进行不必要的重新翻译。

示例

en/example.arb

{
  "@@locale": "en",
  "welcome_message": "欢迎使用我们的 Flutter 应用",
  "@welcome_message": {
    "description": "主屏幕上显示的欢迎消息",
    "context": "问候"
  },
  "login_button": "登录",
  "signup_button": "注册",
  "greeting_with_name": "你好 {name}！",
  "@greeting_with_name": {
    "description": "带有用户姓名的问候消息",
    "placeholders": {
      "name": {
        "type": "String",
        "description": "用户的显示名称"
      }
    }
  },
  "item_count": "{count, plural, =0 {没有项目} one {# 个项目} other {# 个项目}}",
  "@item_count": {
    "description": "显示项目数量的消息，具有适当的复数形式",
    "placeholders": {
      "count": {
        "type": "int",
        "description": "项目的数量"
      }
    }
  }
}

es/example.arb

{
  "@@locale": "es",
  "welcome_message": "Bienvenido a nuestra aplicación Flutter",
  "@welcome_message": {
    "description": "主屏幕上显示的主要欢迎消息",
    "context": "问候"
  },
  "login_button": "Iniciar sesión",
  "signup_button": "Registrarse",
  "greeting_with_name": "¡Hola {name}!",
  "@greeting_with_name": {
    "description": "带有用户姓名的问候消息",
    "placeholders": {
      "name": {
        "type": "String",
        "description": "用户的显示名称"
      }
    }
  },
  "item_count": "{count, plural, =0 {Sin elementos} one {# elemento} other {# elementos}}",
  "@item_count": {
    "description": "显示项目数量的消息，具有适当的复数形式",
    "placeholders": {
      "count": {
        "type": "int",
        "description": "项目的数量"
      }
    }
  }
}

i18n.json

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

i18n.lock

version: 1
checksums:
  88559ecadc7cff52625bd3a47e51dd78:
    welcome_message: 9c56d00796c3c7facba6a25275de5b7b
    login_button: 0029e5a35676c0051e761fcd046ef9ee
    signup_button: 0dd2ae69be4618c1f9e615774a4509ca
    error_network: e0becd5fc88e85a97c6987b96c80fb11
    success_message: e6dcd73052dc41dbe05d86af9887d2c4
    user_profile_title: bee775ff7216747b2111e93cefa57ddc
    settings_screen_title: 8df6777277469c1fd88cc18dde2f1cc3
    cancel_action: 2e2a849c2223911717de8caa2c71bade
    confirm_action: 90930b51154032f119fa75c1bd422d8b
    greeting_with_name: 218521f06746e82ba44d68c8a5bb210c
    item_count: d8d083b56bc155cf0997ea6ae989b83f
    user_status: 903b5a6edde5368dd9089accdc1b1f9d