Flutter国际化工具插件intl_utils的使用

Intl Utils

intl_utils 是一个Dart包，它创建了来自.arb文件的翻译与Flutter应用程序之间的绑定。它为官方Dart Intl库生成样板代码，并在Dart代码中添加键的自动完成功能。

使用方法

你可以直接使用这个包（例如用于持续集成工具或通过CLI），或者让 Visual Studio Code 或 IntelliJ/Android Studio 插件在你修改ARB文件时自动运行它。

配置包

将包配置添加到你的pubspec.yaml文件中。以下是此包的完整配置：

flutter_intl:
  enabled: true # 必须设置为true以激活该包，默认为false
  class_name: S # 可选。设置生成的本地化类的名称，默认为S
  main_locale: en # 可选。设置用于生成本地化文件的主要语言环境，默认为en
  arb_dir: lib/l10n # 可选。设置你的ARB资源文件目录，默认为lib/l10n
  output_dir: lib/generated # 可选。设置生成的本地化文件目录，默认为lib/generated
  use_deferred_loading: false # 可选。必须设置为true以生成延迟加载的本地化代码，默认为false
  localizely: # 如果你使用Localizely平台，则为可选设置。更多信息：https://localizely.com/blog/flutter-localization-step-by-step/?tab=automated-using-flutter-intl
    project_id: # 从https://app.localizely.com/projects页面获取。
    branch: # 如果启用了分支并希望使用非主分支，则从Localizely平台的“Branches”页面获取。
    upload_overwrite: # 如果希望上传时覆盖翻译，请设置为true，默认为false
    upload_as_reviewed: # 如果希望标记上传的翻译为已审核，请设置为true，默认为false
    upload_tag_added: # 可选的新翻译标签列表（例如 ['new', 'New translation']）。默认为空
    upload_tag_updated: # 可选的更新翻译标签列表（例如 ['updated', 'Updated translation']）。默认为空
    upload_tag_removed: # 可选的删除翻译标签列表（例如 ['removed', 'Removed translation']）。默认为空
    download_empty_as: # 设置为空|main|skip，以配置如何从Localizely平台导出空翻译。默认为空
    download_include_tags: # 可选的下载标签列表（例如 ['include', 'Include key']）。如果未设置，则所有字符串键都将被考虑下载。默认为空
    download_exclude_tags: # 可选的排除下载标签列表（例如 ['exclude', 'Exclude key']）。如果未设置，则所有字符串键都将被考虑下载。默认为空
    ota_enabled: # 如果希望使用Localizely Over-the-air功能，请设置为true，默认为false

添加 ARB 文件

为每个需要支持的语言环境添加一个 ARB 文件。将它们添加到项目中的 lib/l10n 文件夹，并按以下方式命名：intl_<LOCALE_ISO_CODE>.arb。例如：intl_en.arb 或 intl_en_GB.arb。你也可以通过在 pubspec.yaml 文件中添加 arb_dir 行来更改 ARB 文件夹。

有关如何在 ARB 文件中格式化键值内容的详细说明，请参考这里。

运行命令

要生成本地化的样板代码，在包含 pubspec.yaml 文件的目录中运行以下命令：

flutter pub run intl_utils:generate

这将在 lib/generated 目录中生成文件。你也可以通过在 pubspec.yaml 文件中添加 output_dir 行来更改输出文件夹。

与 Localizely 的集成

上传主 ARB 文件

flutter pub run intl_utils:localizely_upload_main [--project-id <PROJECT_ID> --api-token <API_TOKEN> --arb-dir <ARB_DIR> --main-locale <MAIN_LOCALE> --branch <BRANCH> --[no-]upload-overwrite --[no-]upload-as-reviewed] --upload-tag-added <UPLOAD_TAG_ADDED> --upload-tag-updated <UPLOAD_TAG_UPDATED> --upload-tag-removed <UPLOAD_TAG_REMOVED>

这将把你的主 ARB 文件上传到 Localizely。所有参数都是可选的。如果没有提供，intl_utils 将使用 pubspec.yaml 文件中的配置或默认值（详情请参阅配置包部分）。

下载 ARB 文件

flutter pub run intl_utils:localizely_download [--project-id <PROJECT_ID> --api-token <API_TOKEN> --arb-dir <ARB_DIR> --download-empty-as <DOWNLOAD_EMPTY_AS> --download-include-tags <DOWNLOAD_INCLUDE_TAGS> --download-exclude-tags <DOWNLOAD_EXCLUDE_TAGS> --branch <BRANCH>]

这将从 Localizely 平台下载所有可用的 ARB 文件，并将其放在 arb-dir 文件夹下。所有参数都是可选的。如果没有提供，intl_utils 将使用 pubspec.yaml 文件中的配置或默认值（详情请参阅配置包部分）。

注意：

• 参数 project-id 如果 pubspec.yaml 文件包含 flutter_intl/localizely 部分下的 project_id 配置，则可以省略。
• 参数 api-token 如果 ~/.localizely/credentials.yaml 文件包含 api_token 配置（例如 api_token: xxxxxx），则可以省略。
• 可选参数 arb-dir 默认值为 lib/l10n，仅在你想将 ARB 文件放置在自定义目录中时才需要设置。

示例代码

为了更好地理解如何使用 intl_utils，请参考 example/README.md 中提供的示例。

完整示例 Demo

以下是一个完整的示例，展示了如何使用 intl_utils 实现国际化：

1. 创建 ARB 文件

   在 lib/l10n 目录下创建两个 ARB 文件：intl_en.arb 和 intl_zh.arb。

   • intl_en.arb

     {
       "@@locale": "en",
       "helloWorld": "Hello World!"
     }

   • intl_zh.arb

     {
       "@@locale": "zh",
       "helloWorld": "你好，世界！"
     }

2. 配置 pubspec.yaml

   flutter_intl:
     enabled: true
     class_name: S
     main_locale: en
     arb_dir: lib/l10n
     output_dir: lib/generated

3. 生成本地化文件

   在终端中运行以下命令：

   flutter pub run intl_utils:generate

4. 使用生成的本地化类

   在你的 Dart 代码中使用生成的 S 类来显示本地化的文本：

   import 'package:flutter/material.dart';
   import 'package:intl/intl.dart';
   import 'generated/l10n.dart';
   
   void main() {
     runApp(MyApp());
   }
   
   class MyApp extends StatelessWidget {
     @override
     Widget build(BuildContext context) {
       return MaterialApp(
         localizationsDelegates: [
           S.delegate,
           GlobalMaterialLocalizations.delegate,
           GlobalWidgetsLocalizations.delegate,
           GlobalCupertinoLocalizations.delegate,
         ],
         supportedLocales: S.delegate.supportedLocales,
         localeResolutionCallback: (locale, supportedLocales) {
           for (var supportedLocale in supportedLocales) {
             if (supportedLocale.languageCode == locale?.languageCode &&
                 supportedLocale.countryCode == locale?.countryCode) {
               return supportedLocale;
             }
           }
           return supportedLocales.first;
         },
         home: MyHomePage(),
       );
     }
   }
   
   class MyHomePage extends StatelessWidget {
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         appBar: AppBar(
           title: Text(S.of(context).helloWorld),
         ),
         body: Center(
           child: Text(S.of(context).helloWorld),
         ),
       );
     }
   }

通过以上步骤，你就可以成功地在 Flutter 应用中实现国际化功能。