Flutter文本同步插件sync_wording的使用

Flutter文本同步插件sync_wording的使用

快速开始

你可以通过一个简单的Google Sheets文件来管理应用的文字。只需创建一个包含键和文字列的表格。此工具会生成文字文件。你的产品负责人可以直接编辑应用的文字。

示例表格

你可以在以下链接找到一个示例表格： 示例表格

表格结构如下：

安装

1. 将 sync_wording 作为开发依赖项安装：

   flutter pub add dev:sync_wording
   

2. 在项目的根目录下创建一个名为 wording_config.yaml 的配置文件。

   配置文件内容如下：

   credentials:
     client_id: "your.google.client.id"
     client_secret: "your.google.client.secret"
   
   sheetId: "your.sheet.id"
   output_dir: "lib/localizations"
   languages:
     en:
       column: 3
     fr:
       column: 4
   

3. 运行命令：

   flutter run sync_wording
   

运行后，会提示你授权访问Google Sheets。

> Task :app:downloadWording
Please open the following address in your browser:
  https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=...

打开URL并授权访问。

占位符

你可以在翻译中指定占位符，并定义它们的类型和格式：

Hello {name} => 创建一个默认的 'Object' 占位符
Hello {name|String} => 创建一个 'String' 占位符
It is {now|DateTime|hh:mm:ss} => 创建一个 'DateTime' 占位符，格式化为 '14:09:15'

分隔符为 |。

这同样适用于复数形式的例子：

{days, plural, zero{today} one{tomorrow} other{in {days|int} days}}

配置选项

表单名称

如果你的Google Sheets文档包含多个表单，所有表单都会被视为有效的输入表单。如果你想只使用其中的一部分，可以在配置文件中指定需要使用的表单名称：

sheetNames: ["Commons", "MyApp"]

键列

默认情况下，包含翻译键的列为第一列（列 ‘A’），但你可以指定另一个键列，如果你的Google Sheets文档有不同的格式：

key_column: 2  # 默认值为 1

值起始行

默认情况下，第一行为标题行，有效的键和翻译从第二行开始。如果你的Google Sheets文档不是这种格式，可以指定从哪一行开始读取翻译：

sheet_start_index: 3  # 默认值为 2

文字验证

在Google Sheets中，你可以添加一列表明是否是有效的翻译：

然后在配置文件中添加：

validation:
  column: 5
  expected: "OK"

如果没有指定 validation，则认为所有内容都是有效的。

本地化类生成

执行此程序将生成 .arb 本地化文件。如果您的Flutter项目已配置使用本地化，并且有一个正确的 l10n.yaml 文件，此程序可以通过运行 flutter gen-l10n 或 fvm flutter gen-l10n 自动生成本地化 Dart 类。你可以在 wording_config.yaml 文件中添加以下内容：

gen_l10n:
  auto_call: true
  with_fvm: true

选项

该工具支持两个选项：

• <code>--config</code>：配置文件路径（可选，默认为 ./wording_config.dart）
• <code>--help</code>：显示帮助信息

完整配置

完整的 wording_config.yaml 文件示例：

credentials:
  client_id: "your.google.client.id"
  client_secret: "your.google.client.secret"
  credentials_file: "credentials.json"    # 可选，默认为 ".google_credentials.json"

sheetId: "your.sheet.id"
output_dir: "lib/localizations"
sheetNames: ["Commons", "MyApp"]          # 可选
sheet_start_index: 2                      # 可选，默认为 2

# 列值：1='A', 2='B', ...
key_column: 1                             # 可选，默认为 1
languages:
  en:
    column: 3
  fr:
    column: 4
validation:                               # 可选
  column: 5
  expected: "OK"

gen_l10n:                                 # 可选
  auto_call: true
  with_fvm: true                          # 可选

示例代码

以下是一个完整的示例代码，展示了如何使用 sync_wording 插件。

import 'package:flutter/material.dart';
import 'package:sync_wording_example/localizations/generated/app_localizations.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'SyncWording Demo',
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(AppLocalizations.of(context)!.hello),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(AppLocalizations.of(context)!.welcome),
            const SizedBox(height: 20),
            Text(AppLocalizations.of(context)!.date(DateTime.now())),
          ],
        ),
      ),
    );
  }
}