Flutter语言辅助插件language_helper的功能使用

描述

language_helper 是一个用于Flutter应用的多语言工具，它具有高效的生成器和自定义的GPT-4翻译器，可以轻松实现应用的本地化。以下是它的主要功能和使用方法。

功能特性

核心功能

• 自动设备语言：首次打开应用时，自动使用当前设备的语言（如果可能）。
• 文本翻译控制：通过LanguageConditions完全控制翻译文本。
• 缺失文本分析：支持分析特定语言中缺少的文本或在应用中存在但在语言数据中不存在的文本。
• 快速提取文本：从所有.dart文件中提取需要翻译的文本，不依赖于build_runner或自定义解析器，非常快速可靠。
• 集成GPT-4翻译器：提供一个基于Chat GPT-4的翻译助手，方便将语言数据翻译成目标语言。

设置与使用

安装配置

1. 添加language_helper到项目

   使用命令行安装包：

   flutter pub add language_helper
   

2. 开发期间初始化空的LanguageHelper

   在main.dart中初始化LanguageHelper：

   final languageHelper = LanguageHelper.instance;
   
   main() async {
     WidgetsFlutterBinding.ensureInitialized();
     await languageHelper.initial(data: []);
     runApp(const MyApp());
   }
   

3. 为需要的字符串添加.tr或.trP

   • 普通翻译：

     Text('Translate this text'.tr)
     

   • 带参数的翻译：

     Text('Hello @{name}'.trP({'name': name}))
     

   • 复数形式：

     Text('We have @{number} dollar'.trP({'number': number}))
     

4. iOS配置

   修改Infi.plist以支持特定语言：

   <key>CFBundleLocalizations</key>
   <array>
      <string>en</string>
      <string>vi</string>
   </array>
   

生成器工作流

Dart Map

• 生成代码：

  dart run language_helper:generate
  

  默认生成路径如下：

  |-- .lib
  |   |--- resources
  |   |    |--- language_helper
  |   |    |    |--- language_data.dart
  |   |    |    |--- languages
  |   |    |    |    |--- _generated.dart   ; This file will be overwritten when re-generating
  

• 添加到项目：

  final languageHelper = LanguageHelper.instance;
  final languageDataProvider = LanguageDataProvider.data(languageData);
  
  main() async {
    await languageHelper.initial(
        data: [languageDataProvider],
    );
  
    runApp(const MyApp());
  }
  

JSON格式

• 生成JSON文件：

  dart run language_helper:generate --json
  

  文件结构如：

  |-- assets
  |   |--- resources
  |   |    |--- language_helper
  |   |    |    |--- codes.json
  |   |    |    |--- languages
  |   |    |    |    |--- _generated.json ; This file will be overwritten when re-generating
  

• 加载JSON资源：

  final languageHelper = LanguageHelper.instance;
  final languageDataProvider = LanguageDataProvider.asset('assets/resources');
  
  main() async {
    await languageHelper.initial(
        data: [languageDataProvider],
    );
  
    runApp(const MyApp());
  }
  

手动流程

创建翻译数据

• Dart Map示例：

  final en = {
    'Translate this text': 'Translate this text',
    'Hello @{name}': 'Hello @{name}',
    'We have @{number} dollar': LanguageConditions(
      param: 'number',
      conditions: {
        '0': 'We have zero dollar',
        '1': 'We have one dollar',
        '_': 'We have @{number} dollars', // 默认值
      }
    ),
  };
  
  const vi = {
    'Translate this text': 'Dịch chữ này',
    'Hello @{name}': 'Xin chào @{name}',
    'We have @{number} dollar': 'Chúng ta có @{number} đô-la', 
  };
  
  LanguageData languageData = {
    LanguageCodes.en: en,
    LanguageCodes.vi: vi,
  };
  

• JSON格式：

  • codes.json包含所有语言代码。
  • 各个语言的具体翻译文件，如en.json、vi.json等。

使用LanguageBuilder更新字符串

在MaterialApp中：

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

  @override
  Widget build(BuildContext context) {
    return LanguageBuilder(
      builder: (context) {
        return MaterialApp(
          localizationsDelegates: languageHelper.delegates,
          supportedLocales: languageHelper.locales,
          locale: languageHelper.locale,
          home: const HomePage(),
        );
      }
    );
  }
}

在组件中：

LanguageBuilder(
    builder: (context) {
        return Scaffold(
          body: Column(
            children: [
              Text('Hello @{name}'.tr),
              Text('We have @{number} dollar'.tr),
            ],
          ),
        );
    },
),

或者更简洁的方式：

Tr((_) => Text('Hello @{name}'.tr)),

控制翻译行为

更改语言

languageHelper.change(LanguageCodes.vi);

添加新的语言数据

languageHelper.addData(LanguageDataProvider.data(newLanguageData));

获取支持的语言列表

final codes = languageHelper.codes; // 包含所有支持的语言代码

监听语言变化

final sub = languageHelper.stream.listen((code) => print(code));
// 不再使用时记得取消订阅以防止内存泄漏
sub.cancel();

分析翻译状态

languageHelper.analyze();

此功能会在initial初始化时自动调用（仅当isDebug=true时）。

高级生成器选项

可以通过命令行参数修改输入输出路径：

dart run language_helper:generate --path=./lib --output=./lib/resources

也可以将LanguageData导出为JSON：

void main() {
  test('', () {
    languageData.exportJson('./assets/resources');
  });
}

数据序列化

将LanguageData转换为JSON：

final json = data.toJson();

从JSON转换回LanguageData：

final data = LanguageDataSerializer.fromJson(json);

自定义GPT-4翻译器

利用提供的模板向Language Helper Translator发送待翻译内容，并确保保持原有的键名和注释格式不变。

其他信息

• 应用会尝试使用设备的默认语言设置作为初始语言；若无法获取，则采用第一个可用语言。
• 插件优化了性能，只重建最外层的LanguageBuilder，除非特别指定了forceRebuild=true。
• 支持多种参数占位符语法（如@{param}），确保翻译过程中正确处理变量替换。

示例代码

完整示例请参阅GitHub仓库中的example/lib/main.dart，该文件展示了如何结合上述功能创建一个多语言支持的应用程序。