Flutter本地化构建插件katana_localization_builder的使用

Katana Localization

简介

本地化包基本上具有以下功能：

• 创建带有特定键和相应翻译文本定义的文件。
• 实现时通过指定特定键来提取并显示当前区域设置的匹配文本。

当时我遇到了以下问题：

• 在实现过程中每次都需要检查定义文件以查看已定义的键。
• 有时会用不同的键对相同的翻译文本进行重复定义，因为不知道哪个键正在被定义。
• 键可能会拼写错误，导致翻译无法正常工作。
• 分享文件并解释结构时很麻烦。
• 有时想使用自动翻译，但过程很繁琐。
• 没有BuildContext可能无法访问。
• 当想在翻译文本中插入变量时，由于是后注入值的形式，理解起来比较困难。

因此，我创建了一个具有以下功能的包来解决上述问题：

• 在Google表格中创建翻译数据。
• 使用 build_runner 进行代码生成。
• 当使用变量时，可以通过方法链输入变量而不会破坏句子顺序。
• 轻松更改语言。可以检测到更改并重新绘制应用程序。
• 可以从任何地方访问，无需BuildContext。

安装

导入以下包以使用 build_runner 进行代码生成：

flutter pub add katana_localization
flutter pub add --dev build_runner
flutter pub add --dev katana_localization_builder

提前准备

提前准备好Google表格。

1. 复制此模板到您的Google云端硬盘：

   • 您可以从 文件 -> 制作副本 复制。

2. 在复制的表格中，点击 文件 -> 共享 -> 与他人共享。

3. 在 共享 "(您创建的表格名)" 窗口中，将 通用访问权限 更改为 任何人有链接即可访问。

如何编写Google表格

Google表格的最左列是 键，每行对应的翻译文本根据区域设置描述在第二列。

如果键以 # 开头，则该行不会被读取。请将其用于注释等。

使用变量

可以在键中输入 {变量名} 来嵌入变量。

相同的 {变量名} 也可以在翻译文本中包含，以便嵌入相应的值并显示。

实现

创建定义文件

创建一个Dart文件，例如 localization.dart。

使用 part 'original filename.localize.dart'; 导入Part文件。

创建一个带有 GoogleSpreadSheetLocalize 注解的类。

类名可以是任意名称，但确保使用 _$ (定义的类名) 作为扩展。

复制并粘贴上面准备好的Google表格URL（例如，https://docs.google.com/spreadsheets/d/1bw7IXEr7BGkZ4U6on0OuF7HQkTMgDSm6u5ThpBkDPeo/edit#gid=551986808）并粘贴进去。

您可以粘贴多个URL作为数组。在这种情况下，将应用所有电子表格的数据。（后面加载的数据优先）

基本翻译可以指定为基准电子表格，附加翻译数据可以针对不同的应用进行指定。

通常，下载的电子表格内容会被缓存，但可以通过递增 version 来更新新内容。

此外，定义该类使用的顶级字段。 字段名越短，以后使用越方便。

// localization.dart
import 'package:katana_localization/katana_localization.dart';

part 'localization.localize.dart';

@GoogleSpreadSheetLocalize(
  [
    "https://docs.google.com/spreadsheets/d/1bw7IXEr7BGkZ4U6on0OuF7HQkTMgDSm6u5ThpBkDPeo/edit#gid=551986808",
  ],
  version: 1,
)
class AppLocalize extends _$AppLocalize { }

final l = AppLocalize();

将翻译数据注册到MaterialApp

使用 AppLocalize 类的对象定义 LocalizeScope 和 MaterialApp。

将刚刚创建的 AppLocalize 对象传递给 localizeScope 的 localize，并将 MaterialApp 放置在 builder 中。

将 AppLocalize 的方法和字段传递给 MaterialApp 的 locale、localizationsDelegates、supportedLocales 和 localeResolutionCallback。

// main.dart

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

import 'localization.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return LocalizeScope(
      localize: l,
      builder: (context, localize) {
        return MaterialApp(
          locale: localize.locale,
          localizationsDelegates: localize.delegates(),
          supportedLocales: localize.supportedLocales(),
          localeResolutionCallback: localize.localeResolutionCallback(),
          title: "Test App",
        );
      },
    );
  }
}

代码生成

通过执行以下命令进行自动代码生成：

flutter pub run build_runner build --delete-conflicting-outputs

当连续执行命令时，缓存可能会保留，导致翻译未反映。

flutter pub run build_runner clean

使用

获取翻译文本

通过执行 AppLocalize 对象作为方法来获取翻译对象。

翻译对象具有在Google表格中定义的键作为字段和方法，因此可以按以下方式获取翻译文本。

print(l().user); // 英文: User、日语: ユーザー

当使用变量时，提供了 $(输入值) 方法，因此在那里输入值。

也可以指定翻译对象作为其输入值。

print(l().$(l().saving).hasBeenCompleted);
// 英文: Saving has been completed.
// 日语: 保存が完了しました。

print(
  l().$(
    l().$(l().saving).of.$(l().data)
  ).hasBeenCompleted
);
// 英文: Saving of Data has been completed.
// 日语: データの保存が完了しました。