Skip to content

7. 国际化

7.1. 示例 21:双语应用

一个双语应用有三类需要翻译的文本:

  • 应用程序文本:标签和消息。它们存放在字典中,每种语言一份;
  • 日期和金额:使用 [intl] 包(见示例 09),按当前语言显示;
  • 来自 [Flutter] 包自身的文本:其窗口上的按钮、日历中的日期和月份。由 [flutter_localizations] 包提供这些。

7.1.1. 字典

{
  "APP": {
    "TITLE": "Exemple 21 - deux langues",
    "LANGUAGE": "Langue"
  },
  "HOME": {
    "HELLO": "Bonjour {{name}} !",
    "TODAY": "Nous sommes le {{date}}.",
    "PRICE": "Une consultation coûte {{price}}.",
    "APPOINTMENTS_zero": "aucun rendez-vous",
    "APPOINTMENTS_one": "un rendez-vous",
    "APPOINTMENTS_other": "{{count}} rendez-vous",
    "ADD": "Ajouter un rendez-vous",
    "REMOVE": "En retirer un",
    "CALENDAR": "Ouvrir le calendrier"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {{minutes}} minute(s)."
  },
  "SERVER": {
    "TITLE": "Traduire une réponse du serveur",
    "EXPLANATION": "Le serveur RdvMedecins ne renvoie que des clés. C'est le client qui les traduit :"
  }
}

每条文本都有一个键 ("HOME.HELLO")。参数写作 [{{name}}];复数文本有多个键,例如 [_zero]、[_one] 和 [_other]。这些是 [JavaScript] [i18next] 库的约定,[React] 和 [Vue.js] 版 [RdvMedecins] 客户端都使用它:案例研究将原样使用它们的字典。英文字典拥有相同的键:

{
  "APP": {
    "TITLE": "Example 21 - two languages",
    "LANGUAGE": "Language"
  },
  "HOME": {
    "HELLO": "Hello {{name}}!",
    "TODAY": "Today is {{date}}.",
    "PRICE": "A consultation costs {{price}}.",
    "APPOINTMENTS_zero": "no appointment",
    "APPOINTMENTS_one": "one appointment",
    "APPOINTMENTS_other": "{{count}} appointments",
    "ADD": "Add an appointment",
    "REMOVE": "Remove one",
    "CALENDAR": "Open the calendar"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {{minutes}} minute(s)."
  },
  "SERVER": {
    "TITLE": "Translating a server response",
    "EXPLANATION": "The RdvMedecins server only sends keys. The client translates them:"
  }
}

7.1.2. 翻译

// =========================================================================
// lib/ex21_i18n/translations.dart - 字典,以及当前语言
// -------------------------------------------------------------------------
// 每种语言都有自己的字典(DICTIONARY),一个随应用一起发布的 JSON 文件
// (assets/i18n/ex21_en.json、ex21_fr.json),其中每段文本
// 都有一个键(KEY)("HOME.HELLO"):
//   - t('HOME.HELLO', {'name': 'Marie'}):当前(CURRENT)语言的
//     文本,其中的 {{name}} 参数会被替换;
//   - t('HOME.APPOINTMENTS', {'count': n}):一段复数形式的文本;我们
//     根据 n 和语言规则选择键 APPOINTMENTS_zero、_one 或 _other
//     (法语中 0 和 1 是单数;英语中
//     只有 1 是单数);
//   - changeLanguage('fr'):加载另一个字典,并通知
//     各个界面(一个 ChangeNotifier),它们会重新翻译自己。
// 这些是 JavaScript 库 i18next 的约定:
// 这些字典与 RdvMedecins 的 Vue.js、Angular 和 React 客户端
// 所用的相同……而服务器只返回键(KEYS)
// ("ERRORS.LOGIN_TAKEN"),也使用它们。
// =========================================================================

import 'dart:convert';

import 'package:flutter/services.dart';
import 'package:flutter/widgets.dart';
import 'package:intl/intl.dart';
import 'package:shared_preferences/shared_preferences.dart';

const languages = ['en', 'fr'];

class Translations extends ChangeNotifier {
  final String _prefix; // 字典:assets/i18n/<prefix>_<language>.json
  final SharedPreferences? _storage;
  String _language = 'en';
  Map<String, Object?> _dictionary = {};

  Translations(this._prefix, [this._storage]);

  String get language => _language;

  // 初始语言:设备上存储的那个,否则是
  // 手机的语言(如果已知),否则是英语
  Future<void> start() async {
    final stored = _storage?.getString('$_prefix.language');
    final device = WidgetsBinding.instance.platformDispatcher.locale.languageCode;
    await changeLanguage(stored ?? (languages.contains(device) ? device : 'en'));
  }

  Future<void> changeLanguage(String language) async {
    // rootBundle:随应用一起发布的文件(pubspec 的 assets 部分)
    final json = await rootBundle.loadString('assets/i18n/${_prefix}_$language.json');
    _dictionary = jsonDecode(json) as Map<String, Object?>;
    _language = language;
    await _storage?.setString('$_prefix.language', language);
    notifyListeners();
  }

  // "HOME.HELLO" -> dictionary['HOME']['HELLO'];缺失时为 null
  String? _lookUp(String key) {
    Object? node = _dictionary;
    for (final part in key.split('.')) {
      node = node is Map<String, Object?> ? node[part] : null;
    }
    return node is String ? node : null;
  }

  String t(String key, [Map<String, Object?> params = const {}]) {
    String? text;
    final count = params['count'];
    if (count is int) {
      // Intl.pluralLogic:复数形式,依据语言的规则
      text = Intl.pluralLogic(
        count,
        locale: _language,
        zero: _lookUp('${key}_zero'),
        one: _lookUp('${key}_one'),
        other: _lookUp('${key}_other'),
      );
    }
    text ??= _lookUp(key);
    // 未知的键会原样显示:缺失的内容一眼就能看出来
    if (text == null) return key;
    // {{name}} -> name 参数的值
    return text.replaceAllMapped(RegExp(r'\{\{(\w+)\}\}'), (m) => '${params[m[1]] ?? m[0]}');
  }
}
  • 第 30–34 行:翻译:一个 [ChangeNotifier] (语言改变时,各屏幕会被重建),它保存当前语言及其字典;
  • 第 42–45 行:初始语言:存储在设备上的语言,否则是手机的语言(如果已知),否则是英语;
  • 第 48–54 行:更改语言:加载字典,这是一个随应用一起打包的 JSON 文件([rootBundle.loadString] 从 [assets] 部分读取一个文件,该部分位于 [pubspec.yaml] 中),解码它([jsonDecode]),保存所选语言,并更新各屏幕;
  • 第 58–63 行:在字典中查找键“HOME.HELLO”:它逐段遍历嵌套的 JSON 对象。[node is Map<String, Object?> ? ... : null]:一次类型检查,它会在检查为真的分支中“提升”该变量的类型;
  • 第 66–83 行:翻译。对于复数(整数参数 [count]),[Intl.pluralLogic] 根据语言规则选择形式:在法语中,0 和 1 是单数;在英语中,只有 1 是单数。未知的键会原样显示:你可以立刻看出缺少什么。最后,每个 [{{name}}] 都会被替换为参数的值。

为什么不使用官方的 [Flutter] 工具?[Flutter] 提供了一个生成器([flutter gen-l10n]),它根据 [.arb] 文件生成一个类,每条文本对应一个方法([AppLocalizations.of(context).hello('Marie')]):键在编译时得到验证。对于所有文本都能预先确定的应用,这是最佳方案。但我们的服务器返回的是键 (“ERRORS.LOGIN_TAKEN”),需要在运行时翻译:用键来查询的字典要适合得多,而且使我们能与其他客户端共享字典。

7.1.3. 已翻译的页面

// =========================================================================
// lib/ex21_i18n/main.dart - 一个双语应用
// -------------------------------------------------------------------------
//   - 应用的文本(TEXTS):字典(translations.dart),
//     通过 provider 提供给所有界面(见示例 20);
//   - 日期和金额:intl 包,使用当前语言
//     (见示例 09);
//   - Flutter 自身(ITSELF)的文本(日历、它的按钮……):
//     flutter_localizations 包的本地化 "delegates",
//     它们跟随 MaterialApp 的 locale 属性。
// 切换语言会重新翻译整个界面,无需重启。
// =========================================================================

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:intl/date_symbol_data_local.dart';
import 'package:intl/intl.dart';
import 'package:provider/provider.dart';
import 'package:shared_preferences/shared_preferences.dart';

import 'translations.dart';

// RdvMedecins 服务器会返回的内容(见关于黑盒的一章)
const serverResponses = [
  (statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: <String, String>{}),
  (statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: {'minutes': '15'}),
];

// context.t('KEY'):一个快捷方式,通过 BuildContext 的扩展实现
extension Translate on BuildContext {
  String t(String key, [Map<String, Object?> params = const {}]) => watch<Translations>().t(key, params);
}

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initializeDateFormatting();
  final translations = Translations('ex21', await SharedPreferences.getInstance());
  await translations.start();
  runApp(ChangeNotifierProvider.value(value: translations, child: const Application()));
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      // onGenerateTitle:应用的标题,已翻译
      onGenerateTitle: (context) => context.t('APP.TITLE'),
      theme: ThemeData(colorSchemeSeed: Colors.indigo),
      locale: Locale(context.watch<Translations>().language),
      supportedLocales: [for (final l in languages) Locale(l)],
      localizationsDelegates: GlobalMaterialLocalizations.delegates,
      home: const TranslatedPage(),
    );
  }
}

class TranslatedPage extends StatefulWidget {
  const TranslatedPage({super.key});

  @override
  State<TranslatedPage> createState() => _TranslatedPageState();
}

class _TranslatedPageState extends State<TranslatedPage> {
  int _count = 2;
  final _today = DateTime.now();

  @override
  Widget build(BuildContext context) {
    final translations = context.watch<Translations>();
    final language = translations.language;
    // 使用当前(CURRENT)语言的格式化器
    final date = DateFormat.yMMMMEEEEd(language).format(_today);
    final price = NumberFormat.currency(locale: language, name: 'EUR', symbol: '€').format(1234.5);

    return Scaffold(
      appBar: AppBar(
        title: Text(context.t('APP.TITLE')),
        actions: [
          // 语言:"分段" 按钮
          Padding(
            padding: const EdgeInsets.only(right: 8),
            child: SegmentedButton<String>(
              showSelectedIcon: false,
              segments: [for (final l in languages) ButtonSegment(value: l, label: Text(l.toUpperCase()))],
              selected: {language},
              onSelectionChanged: (choice) => translations.changeLanguage(choice.first),
            ),
          ),
        ],
      ),
      body: ListView(
        padding: const EdgeInsets.all(16),
        children: [
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(context.t('HOME.HELLO', {'name': 'Marie'})),
                  Text(context.t('HOME.TODAY', {'date': date})),
                  Text(context.t('HOME.PRICE', {'price': price})),
                  const SizedBox(height: 8),
                  // count:选择复数形式,并替换 {{count}}
                  Text(
                    context.t('HOME.APPOINTMENTS', {'count': _count}),
                    style: const TextStyle(fontWeight: FontWeight.bold),
                  ),
                  Wrap(
                    spacing: 8,
                    children: [
                      TextButton(onPressed: () => setState(() => _count++), child: Text(context.t('HOME.ADD'))),
                      TextButton(
                        onPressed: _count == 0 ? null : () => setState(() => _count--),
                        child: Text(context.t('HOME.REMOVE')),
                      ),
                    ],
                  ),
                  // Flutter 的日历:它的文本跟随 MaterialApp 的语言
                  OutlinedButton.icon(
                    icon: const Icon(Icons.calendar_month),
                    label: Text(context.t('HOME.CALENDAR')),
                    onPressed: () =>
                        showDatePicker(context: context, firstDate: DateTime(2026), lastDate: DateTime(2027, 12, 31)),
                  ),
                ],
              ),
            ),
          ),
          Card(
            child: Padding(
              padding: const EdgeInsets.all(12),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(context.t('SERVER.TITLE'), style: Theme.of(context).textTheme.titleSmall),
                  Text(context.t('SERVER.EXPLANATION')),
                  const SizedBox(height: 8),
                  // 服务器的键就是字典中的一个键;params 提供它的参数
                  for (final r in serverResponses) ...[
                    Text('${r.statusCode} ${r.key}', style: const TextStyle(fontFamily: 'RobotoMono', fontSize: 12)),
                    Text('→ ${context.t(r.key, r.params)}'),
                    const SizedBox(height: 6),
                  ],
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}
  • 第 30–31 行:[BuildContext] 的一个扩展(见示例 09):[context.t('KEY')] 读取上方提供的翻译,订阅更新,并执行翻译;
  • 第 36–38 行:初始化:所有语言的星期名称和月份名称,然后是翻译;
  • 第 39 行:[ChangeNotifierProvider.value] 提供一个已经(由 [main])创建好的对象;
  • 第 50 行:应用标题,已翻译;
  • 第 52–54 行:[Flutter] 自身的语言跟随应用的语言;
  • 第 76–77 行:日期和价格,按当前语言格式化,然后作为参数传给文本字符串;
  • 第 86–90 行:顶部栏中的语言选择;
  • 第 110 行:[count] 选择复数形式并替换 [{{count}}];
  • 第 124–128 行:[Flutter] 的日历:其文本跟随 [MaterialApp] 的语言;
  • 第 144–146 行:服务器 [RdvMedecins] 会返回的内容:一个键及其参数。服务器返回的键就是字典中的键。

英语(左图);添加之后的法语(中图);法语日历(右图):

切换语言会重新渲染整个屏幕,无需重启,也不需要向服务器发出任何请求。所选语言存储在设备上。