Flutter语言翻译插件tradutor的使用

tradutor 是一个简化国际化过程的Flutter包。它通过提取消息并生成包含所需消息的友好方式访问的Dart文件。

String get translator => "tradutor";

特性

• 简单的消息。
• 带多个参数的消息。
• 简单消息列表。
• 多个参数的消息列表。
• 支持的消息类型：
  • 复数形式。
  • 日期。
  • 数值。
  • 映射。
• 可选参数支持。
• JSON 和 YAML 文件。
• 支持嵌套消息。
• 支持热重载。

安装

在 pubspec.yaml 中添加以下依赖：

dependencies: 
    flutter_localizations: 
        sdk: flutter 

dev_dependencies:
    tradutor: ^0.10.0

使用

在项目目录内打开终端并运行以下命令：

flutter pub run tradutor:generate

所有支持的参数：

• --source "DIRECTORY PATH" 或 --s "DIRECTORY PATH": 包含所有 JSON/YAML 文件的源文件夹（默认为 “./i18n”）；
• --output "FILE PATH" 或 --o "FILE PATH": 包含所有字符串的输出文件（默认为 “./lib/i18n.dart”）；
• --fallback "LANGUAGE" 或 --f "LANGUAGE": 提供一个默认语言，在当前运行系统未提供翻译时使用（默认为 “en_US”）；
• --watch: 监视 JSON/YAML 文件的编辑，并根据需要进行重建。
• --class-name "NAME" 或 --c "NAME": 允许更改生成的 Dart 类名（默认为 “I18n”）。

完整示例：flutter packages pub run tradutor:generate -s "/i18n" -o "/lib/i18n.dart" -f "en_US" -c "I18n" --watch

JSON 文件

创建命名格式为语言代码（小写）和国家代码（大写）的 JSON 文件。例如：pt_BR.json, en_US.json 等。

en_US.json

{
    "simpleMessage": "This is a simple Message",
    "messageWithParameters": "Hi {name}, Welcome you!",
    "brazilFlagColors": ["Green", "Yellow", "Blue", "White"],
    "simpleWhiteCakeIngredients": [
        "{whiteSugar} cup white sugar",
        "{butter} cup butter",
        "{eggs} eggs",
        "{vanilla} teaspoons vanilla extract",
        "{flour} cups all-purpose flour",
        "{bakingPowder} teaspoons baking powder",
        "{milk} cup milk"
    ],
    "homePage": {
        "title": "Home Page"
    },
    "counter.one": "Button clicked 1 time",
    "counter.other": "Button cliked {quantity} times"
}

YAML 文件

创建命名格式为语言代码（小写）和国家代码（大写）的 YAML 文件。例如：pt_BR.yaml, en_US.yaml 等。

simpleMessage: これは簡単なメッセージです
messageWithParameters: "{name}様、ようこそ！"
brazilFlagColors:
- 緑
- 黄色
- 青い
- 白い
simpleWhiteCakeIngredients:
- "白砂糖{whiteSugar}カップ"
- "バター{butter}カップ"
- "卵{eggs}個"
- "バニラエッセンス小さじ{vanilla}"
- "薄力粉{flour}カップ"
- "小さじ{bakingPowder}杯のベーキングパウダー"
- "牛乳{milk}カップ"
homePage:
  title: ホームページ
counter.other: ボタンが{quantity}回クリックされた

嵌套消息

消息可以嵌套。最终的消息名称将被转换为驼峰式格式（以小写字母开头，每个后续键首字母大写）。

{
  "this" : {
    "is" : {
      "a": {
        "nested": "Message"
      }
    }
  }
}

生成的 Dart getter:

String get thisIsANested => 'Message';

可选参数

使用 {?name=value} 将参数设置为可选。=value 是可选的，省略时将使用空字符串。

支持的消息类型

消息中的所有参数都必须用花括号包围。参数按字母顺序排序。

简单消息

{ 
    "simpleMessage": "This is a simple Message"
}

生成的 Dart getter:

String get simpleMessage => 'This is a simple Message';

带参数的消息

{
    "messageWithParameters": "Hi {name}, Welcome you!"
}

生成的 Dart 方法:

String messageWithParameters(dynamic name) => 'Hi ${name}, Welcome you!';

简单消息列表

定义一个字符串数组。

{
    "brazilFlagColors": ["Green", "Yellow", "Blue", "White"]
}

生成的 Dart getter:

List<String> get brazilFlagColors => ['Green', 'Yellow', 'Blue', 'White'];

多个参数的消息列表

{
    "simpleWhiteCakeIngredients": [
        "{whiteSugar} cup white sugar",
        "{butter} cup butter",
        "{eggs} eggs",
        "{vanilla} teaspoons vanilla extract",
        "{flour} cups all-purpose flour",
        "{bakingPowder} teaspoons baking powder",
        "{milk} cup milk"
    ],
}

生成的 Dart 方法:

List<String> simpleWhiteCakeIngredients(
          dynamic bakingPowder, 
          dynamic butter, 
          dynamic eggs, 
          dynamic flour, 
          dynamic milk, 
          dynamic vanilla, 
          dynamic whiteSugar) =>
      [
        '${whiteSugar} cup white sugar',
        '${butter} cup butter',
        '${eggs} eggs',
        '${vanilla} teaspoons vanilla extract',
        '${flour} cups all-purpose flour',
        '${bakingPowder} teaspoons baking powder',
        '${milk} cup milk'
      ];

复数形式的消息

最后的消息名称必须是 zero, one, two, few, many 或 other。参见 语言复数规则。

{
  "counter.one": "Button clicked 1 time",
  "counter.other": "Button cliked {quantity} times"
}

或者

{
  "counter": {
    "one": "Button clicked 1 time",
    "other": "Button cliked {quantity} times"
  }
}

必须提供 other 的复数形式。

quantity 是用于根据其值格式化消息的参数。

生成的 Dart 方法:

String counter(int quantity) => Intl.plural(
        quantity,
        locale: 'en_US',
        one: 'Button clicked 1 time',
        other: 'Button cliked ${quantity} times',
      );

映射消息

消息名称以 % 开头。

{
  "%eyeColor": {
    "FAMALE": "She has {color} eyes",
    "MALE": "He has {color} eyes"
  }
}

生成的 Dart 方法:

String eyeColor(String key, dynamic color) {
    switch (key) {
      case 'FAMALE':
        return 'She has ${color} eyes';
      case 'MALE':
        return 'He has ${color} eyes';
      default:
        return null;
    }
  }

key 是用于根据其值格式化消息的参数。

日期消息

消息名称以 # 开头。

{
    "#fullDate": "MM dd, yyyy h:mm:ss a"
}

生成的 Dart 方法:

static final _fullDateFormatter = DateFormat('MM dd, yyyy h:mm:ss a', 'en_US');
String fullDate(DateTime date) => _fullDateFormatter.format(date);

参见 DateFormat 文档。

数值消息

消息名称以 $ 开头。

{
    "$currencyMessage": "\\$#,##0.00"
}

生成的 Dart 方法:

static final _currencyMessageFormatter = NumberFormat('\$#,##0.00', 'en_US');
String currencyMessage(num number) => _currencyMessageFormatter.format(number);

参见 NumberFormat 文档。

生成的 Dart 文件 (i18n.dart) 的使用

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';

import 'i18n.dart';

void main() => runApp(App());

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final i18n = I18n.delegate;

    return MaterialApp(
      title: 'Tradutor',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const HomePage(),
      localizationsDelegates: [
        i18n,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
      ],
      supportedLocales: i18n.supportedLocales,
      localeResolutionCallback: i18n.resolution(
        fallback: const Locale('en', 'US'),
      ),
    );
  }
}

class HomePage extends StatefulWidget {
  const HomePage({
    Key key,
  }) : super(key: key);

  @override
  _HomePageState createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  var _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    final i18n = I18n.of(context);

    return Scaffold(
      appBar: AppBar(
        title: Text(i18n.homePage),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(i18n.counter(_counter)),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        child: const Icon(Icons.add),
      ),
    );
  }
}

转义花括号和美元符号

语言选项

@parent

使用 [@parent](/user/parent) 表示语言是父语言。

pt_PT.json

{
    "[@parent](/user/parent)": true,
}

pt_PT 是 pt_BR, pt_AO, pt_TL 等的父语言。如果找不到某些子语言，则将使用 pt_PT。

@textDirection

使用 [@textDirection](/user/textDirection) 指示文本流动的方向。有效值为 ltr（默认）和 rtl。

he_IL.json

{
    "[@textDirection](/user/textDirection)": "rtl",
}