Flutter本地化管理插件 auto_localized 的使用

auto_localized 是一个简化 Flutter 本地化的插件，通过代码生成来实现。这种方法有许多优点，如运行时安全性、更好的性能等。生成器会检查翻译文件中的缺失键、空白值等，并输出易于使用的 Dart 字段或方法。

主要特性

• 运行时验证
• 无需 BuildContext 即可获取翻译
• 安全参数
• 支持的文件类型：JSON, YAML

开始使用

原生设置（iOS）

在 iOS 上，需要在 ios/Runner/Info.plist 中添加支持的语言环境：

<key>CFBundleLocalizations</key>
<array>
  <string>pl</string>
  <string>en</string>
  <string>sk</string>
</array>

pubspec.yaml 设置

添加依赖到你的 pubspec.yaml 文件中：

dependencies:
  auto_localized: ^latest_version

dev_dependencies:
  build_runner: ^latest_version
  auto_localized_generator: ^latest_version

注意：不需要手动添加 flutter_localizations，因为 auto_localized 已经为你处理了这一点。

如果翻译文件存储在 lib 目录之外（推荐），例如：

lang/
├── en.yaml
├── pl.json
└── sk.json
lib/
build.yaml
pubspec.yaml

你需要告诉 build_runner 关于这些目录的信息，通过覆盖默认的 sources。创建或更新根目录下的 build.yaml 文件并添加以下部分：

targets:
  $default:
    sources:
      - $package$
      - lib/**
      - lang/**  # <-- your translations directory 

配置

创建一个新的 Dart 文件，并用 AutoLocalized 注解它：

import 'package:auto_localized/annotations.dart';

@AutoLocalized(
  locales: [
    AutoLocalizedLocale(
      languageCode: 'pl',
      translationsFiles: ['lang/pl.json'],
    ),
    AutoLocalizedLocale(
      languageCode: 'en',
      countryCode: 'US',
      translationsFiles: ['lang/en.json'],
    ),
    AutoLocalizedLocale(
      languageCode: 'sk',
      translationsFiles: ['lang/sk.json'],
    ),
  ],
)
class $Strings {}

注意：类名必须以 $ 开头，例如上面的例子中，最终生成的类名为 Strings。

生成代码

运行以下命令生成代码：

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

或者，如果你想在每次文件更改后自动构建：

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

使用

在应用声明中添加生成的配置字段 supportedLocales 和 localizationsDelegates。如果你想在没有上下文的情况下获取翻译，需要用 AutoLocalizedApp 包裹 MaterialApp：

return AutoLocalizedApp(
  child: MaterialApp(
    supportedLocales: context.supportedLocales,
    localizationsDelegates: context.localizationsDelegates,
  ),
);

你可以通过 AutoLocalizedData 类或 AutoLocalizedContextExtension 访问这些字段。

示例代码

下面是一个完整的示例，展示了如何使用 auto_localized 插件：

import 'package:auto_localized/auto_localized.dart';
import 'package:example/localization.al.dart'; // 确保这是你生成的文件路径
import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return AutoLocalizedApp(
      child: MaterialApp(
        title: 'Auto Localized Example',
        theme: ThemeData(
          primarySwatch: Colors.blue,
          visualDensity: VisualDensity.adaptivePlatformDensity,
        ),
        supportedLocales: context.supportedLocales,
        localizationsDelegates: context.localizationsDelegates,
        home: HomePage(),
      ),
    );
  }
}

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(
          Strings.welcomeName.get('Marcin', ':D'),
        ),
      ),
      body: Center(
        child: Text(
          Strings.getTestMessage(),
        ),
      ),
    );
  }
}

其他功能

安全参数

你可以定义最多5个参数用于翻译字符串。例如：

{
  "welcome_message" : "Welcome {1}!, You have {2} points."
}

使用时：

Strings.welcomeMessage('Marcin', '3');

当前语言环境

你可以访问当前的语言环境：

AutoLocalization.instance.locale;

语言环境变更回调

如果你希望在语言环境变化时执行某些任务，可以使用 AutoLocalization.addOnLocaleChangeCallback：

AutoLocalization.addOnLocaleChangeCallback((locale) { 
  // 执行任务
});

取消监听：

AutoLocalization.removeOnLocaleChangeCallback(onLocaleChange);

以上就是 auto_localized 插件的基本使用方法。希望对你有所帮助！