Flutter本地化翻译插件phrase的使用

Flutter本地化翻译插件Phrase的使用

1. 简介

phrase 是一个用于Flutter应用的本地化翻译插件，支持通过空中下载（OTA）更新翻译内容。它依赖于 intl 库，并且使用代码生成来处理 ARB 文件。本文将详细介绍如何安装、配置和使用 phrase 插件，以及一些自定义选项。

2. 安装

首先，确保你的项目已经添加了对 intl 库的支持。phrase 依赖于 0.18.0 版本的 intl 库，请按照官方文档中的指南为你的应用添加国际化支持。

在 pubspec.yaml 文件中添加 phrase 依赖：

dependencies:
  phrase: ^2.0.0
  intl: ^0.18.0
  flutter_localizations:
    sdk: flutter
  ...

flutter:
  generate: true
  ...

为了保持生成的本地化文件最新，你可以运行以下命令：

$ flutter pub run phrase

如果你使用 build_runner，可以运行以下命令来自动监控文件变化并生成代码：

$ flutter pub run build_runner watch

3. 使用

初始化 Phrase Strings

在 main.dart 文件中初始化 Phrase，并设置分发ID和环境ID。你需要从 Phrase 平台获取这些ID。

import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:flutter_gen/gen_l10n/phrase_localizations.dart';
import 'package:phrase/phrase.dart';

void main() {
  // 初始化 Phrase，传入分发ID和环境ID
  Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]");
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      localizationsDelegates: PhraseLocalizations.localizationsDelegates,
      supportedLocales: PhraseLocalizations.supportedLocales,
    );
  }
}

访问翻译内容

你可以在应用中像以前一样访问翻译内容，但现在的翻译会定期从 Phrase 平台检查更新并在后台下载。

Text(AppLocalizations.of(context)!.helloWorld);

4. 自定义

更新行为

默认情况下，Phrase 会在每次应用启动时检查并更新翻译内容。你可以禁用此行为，并手动触发更新：

// 禁用自动更新
Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", checkForUpdates: false);

// 手动触发更新
Phrase.updateTranslations(context).then((_) => print("Done!"));

API 主机

Phrase 默认使用欧洲主机。如果你需要使用美国主机，可以在初始化时指定：

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", host: PhraseHost.us);

自定义应用版本

SDK 会根据应用版本返回与发布约束匹配的翻译版本。如果你的应用不使用语义化版本号，可以通过手动覆盖应用版本：

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", customAppVersion: "1.2.3");

请求超时

默认情况下，OTA 请求的超时时间为 30 秒。你可以通过配置 Phrase 的初始化参数来更改这个值：

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", defaultTimeout: const Duration(seconds: 10));

你也可以在手动更新翻译时设置超时时间，这将覆盖初始化时设置的超时值：

Phrase.updateTranslations(context, timeout: const Duration(seconds: 10));

5. 使用键字符串字面量访问 OTA 翻译

你可以通过包含翻译键的字符串字面量来访问 OTA 翻译。例如，对于以下 ARB 文件中的翻译：

{
  "textSimple": "Simple Text"
}

你可以使用 getText 方法来获取翻译值：

Text(AppLocalizations.of(context).getText('textSimple'))

而不是直接访问属性：

Text(AppLocalizations.of(context).textSimple)

带参数的翻译

你还可以使用 getText 方法来处理带参数的翻译。例如，对于以下 ARB 文件中的翻译：

{
  "textWithDate": "Text with date: {date}",
  "@textWithDate": {
    "description": "Text with date parameter",
    "placeholders": {
      "date": {
        "type": "DateTime",
        "format": "yMd"
      }
    }
  }
}

你可以通过传递参数来获取翻译值：

Text(AppLocalizations.of(context).getText(
  'textWithDate',
  args: {'date': DateTime.utc(1996, 7, 10)},
))

注意，参数键必须与翻译占位符名称匹配，否则会导致运行时错误。

设置回退值

getText 方法还支持为未找到的键设置回退值。这对于基于其他变量的键非常有用：

Text(AppLocalizations.of(context).getText(
  myKeyVariable,
  fallbackValue: 'fallback for unknownKey',
))

6. 完整示例 Demo

以下是一个完整的示例，展示了如何在 Flutter 应用中使用 phrase 插件进行本地化翻译。

import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:flutter_gen/gen_l10n/phrase_localizations.dart';
import 'package:phrase/phrase.dart';

void main() {
  // 初始化 Phrase，传入分发ID和环境ID
  Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]");

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      localizationsDelegates: PhraseLocalizations.localizationsDelegates,
      supportedLocales: PhraseLocalizations.supportedLocales,
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(AppLocalizations.of(context)!.appTitle),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              AppLocalizations.of(context)!.helloWorld,
              style: TextStyle(fontSize: 24),
            ),
            SizedBox(height: 20),
            Text(
              AppLocalizations.of(context)!.getText(
                'textWithDate',
                args: {'date': DateTime.now()},
              ),
              style: TextStyle(fontSize: 18),
            ),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: () {
                // 手动触发翻译更新
                Phrase.updateTranslations(context).then((_) {
                  ScaffoldMessenger.of(context).showSnackBar(
                    SnackBar(content: Text('Translations updated!')),
                  );
                });
              },
              child: Text('Update Translations'),
            ),
          ],
        ),
      ),
    );
  }
}