flutter-setup-localization

Flutter 应用国际化（i18n）指南

目录

• 核心概念
• 配置流程
• 开发实现流程
• 高级格式化语法
• 完整示例

核心概念

Flutter 主要通过 flutter_localizations 和 intl 这两个 Package 来实现国际化（i18n）与本地化（l10n）。标准的做法是用 ARB（App Resource Bundle，扩展名为 .arb）文件来定义多语言字符串，项目构建时会自动把它们编译为类型安全的 AppLocalizations 类，方便在 Widget 树中直接调用。

配置流程

在 Flutter 项目中初始化国际化支持时，可以按以下清单逐项配置与勾选：

• [ ] 任务进度
  • [ ] 1. 在 pubspec.yaml 中添加项目依赖。
  • [ ] 2. 开启 generate 代码自动生成选项。
  • [ ] 3. 创建 l10n.yaml 配置文件。
  • [ ] 4. 配置 MaterialApp 或 CupertinoApp 入口。

1. 添加依赖

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

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 库。随后将对应的 Delegate 和支持的 Locale 列表注入到 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）中添加基础字符串，并补充 description 说明文案背景。
• 如果是修改已有文案： 在所有已支持语言的 .arb 文件中找到对应的 Key 并更新其内容。

{
  "helloWorld": "Hello World!",
  "@helloWorld": {
    "description": "程序员入门经典问候语"
  }
}

在其他语言对应的文件中同步添加配置（例如 app_es.arb）：

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

2. 生成本地化类

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

flutter pub get

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

3. 在 Widget 中调用本地化文案

在 Widget 树中通过 AppLocalizations.of(context) 获取本地化字符串。请确保调用该方法的 Widget 处于 MaterialApp 的子树中。

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

高级格式化语法

支持通过占位符来实现动态数据填充、复数形式（Plural）以及条件选择（Select）。

动态占位符（Placeholders）

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

"hello": "Hello {userName}",
"@hello": {
  "description": "带单个参数的问候文案",
  "placeholders": {
    "userName": {
      "type": "String",
      "example": "Bob"
    }
  }
}

复数形式（Plurals）

使用 plural 语法处理与数量相关的文案变化。其中 other 情况为必选的分支。

"nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
"@nWombats": {
  "description": "带复数逻辑的文案",
  "placeholders": {
    "count": {
      "type": "num",
      "format": "compact"
    }
  }
}

条件选择（Selects）

使用 select 语法实现条件分支判断，例如根据性别切换代词。

"pronoun": "{gender, select, male{he} female{she} other{they}}",
"@pronoun": {
  "description": "带性别区分的代词文案",
  "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)),
      ],
    );
  }
}