flutter-setup-localization

Flutter 应用国际化

目录

• 核心概念
• 设置工作流
• 实现工作流
• 高级格式化
• 示例

核心概念

Flutter 通过 flutter_localizations 和 intl 包处理国际化（i18n）和本地化（l10n）。标准方法使用应用资源包（.arb）文件定义本地化字符串，然后编译成生成的 AppLocalizations 类，以便在 widget 树中进行类型安全的访问。

设置工作流

在 Flutter 项目中初始化国际化时，复制并跟踪此清单：

• [ ] 任务进度
  • [ ] 1. 在 pubspec.yaml 中添加依赖。
  • [ ] 2. 启用 generate 标志。
  • [ ] 3. 创建 l10n.yaml 配置文件。
  • [ ] 4. 配置 MaterialApp 或 CupertinoApp。

1. 添加依赖

将所需的本地化包添加到项目中。在终端中执行以下命令：

flutter pub add flutter_localizations --sdk=flutter
flutter pub add intl:any

确认你的 pubspec.yaml 在 dependencies 下包含以下内容：

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

2. 启用代码生成

打开 pubspec.yaml，在 flutter 部分启用 generate 标志以自动化本地化任务：

flutter:
  generate: true

3. 创建配置文件

在 Flutter 项目的根目录中创建一个名为 l10n.yaml 的新文件。定义输入目录、模板文件和输出文件：

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true

4. 配置应用入口点

在 main.dart 中导入生成的本地化类和 flutter_localizations 库。将委托和支持的区域设置注入到你的 MaterialApp 或 CupertinoApp 中。

import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // 如果 synthetic-package 为 false，则调整路径

// ... 在 build 方法内部
return MaterialApp(
  localizationsDelegates: const [
    AppLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en'), // 英语
    Locale('es'), // 西班牙语
  ],
  home: const MyHomePage(),
);

实现工作流

在添加或修改本地化内容时遵循此工作流。

1. 定义 ARB 文件

• 如果创建新内容： 将基本字符串添加到模板文件（lib/l10n/app_en.arb）中。包含描述以提供上下文。
• 如果编辑现有内容： 在所有支持的 .arb 文件中找到键并更新值。

{
  "helloWorld": "Hello World!",
  "@helloWorld": {
    "description": "The conventional newborn programmer greeting"
  }
}

为其他区域设置创建对应文件（例如 app_es.arb）：

{
  "helloWorld": "¡Hola Mundo!"
}

2. 生成本地化类

运行以下命令以触发代码生成：

flutter pub get

反馈循环： 运行验证器 -> 检查终端输出中的 ARB 语法错误 -> 修复缺失的逗号或不匹配的占位符 -> 重新运行 flutter pub get。

3. 使用本地化字符串

使用 AppLocalizations.of(context) 在 widget 树中访问本地化字符串。确保调用此方法的 widget 是 MaterialApp 的后代。

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

高级格式化

使用占位符处理动态数据、复数和条件选择。

占位符

在花括号内定义参数，并在元数据对象中指定其类型。

"hello": "Hello {userName}",
"@hello": {
  "description": "A message with a single parameter",
  "placeholders": {
    "userName": {
      "type": "String",
      "example": "Bob"
    }
  }
}

复数

使用 plural 语法处理基于数量的字符串变体。other 情况是必需的。

"nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
"@nWombats": {
  "description": "A plural message",
  "placeholders": {
    "count": {
      "type": "num",
      "format": "compact"
    }
  }
}

选择

使用 select 语法处理条件字符串，例如性别文本。

"pronoun": "{gender, select, male{he} female{she} other{they}}",
"@pronoun": {
  "description": "A gendered message",
  "placeholders": {
    "gender": {
      "type": "String"
    }
  }
}

示例

完整的 l10n.yaml

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: true
use-escaping: true

完整的 Widget 实现

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

class GreetingWidget extends StatelessWidget {
  final String userName;
  final int notificationCount;

  const GreetingWidget({
    super.key, 
    required this.userName, 
    required this.notificationCount,
  });

  @override
  Widget build(BuildContext context) {
    final l10n = AppLocalizations.of(context)!;

    return Column(
      children: [
        Text(l10n.hello(userName)),
        Text(l10n.nWombats(notificationCount)),
      ],
    );
  }
}