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'; // Adjust path if synthetic-package is false

// ... inside build method
return MaterialApp(
  localizationsDelegates: const [
    AppLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en'), // English
    Locale('es'), // Spanish
  ],
  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. 使用本地化字符串

在 widget 树中使用 AppLocalizations.of(context) 访问本地化字符串。确保调用此方法的 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)),
      ],
    );
  }
}