Flutter 国际化与本地化：intl、ARB 与多语言应用

const localeZh = Locale('zh', 'CN'); // 简体中文（中国）
const localeEn = Locale('en');        // 英语
const localeAr = Locale('ar');        // 阿拉伯语（触发 RTL）

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any
  intl_translation: any # 可选，用于某些工具链

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';

MaterialApp(
  localizationsDelegates: const [
    GlobalMaterialLocalizations.delegate, // Material 组件内置文案
    GlobalWidgetsLocalizations.delegate,  // Widget 层（如文本方向）
    GlobalCupertinoLocalizations.delegate,// Cupertino 组件内置文案
  ],
  supportedLocales: const [
    Locale('zh', 'CN'),
    Locale('en'),
    Locale('ar'),
  ],
  locale: const Locale('zh', 'CN'), // 手动指定；不指定则跟随系统
  home: const HomePage(),
)

// lib/l10n/app_zh.arb
{
  "@@locale": "zh",
  "appTitle": "我的应用",
  "@appTitle": {
    "description": "应用标题"
  },
  "welcome": "欢迎，{name}！",
  "@welcome": {
    "description": "带参数的问候语",
    "placeholders": {
      "name": { "type": "String" }
    }
  },
  "itemCount": "{count, plural, =0{没有项目} =1{1 个项目} other{{count} 个项目}}",
  "@itemCount": {
    "placeholders": {
      "count": { "type": "int" }
    }
  }
}

// lib/l10n/app_en.arb
{
  "@@locale": "en",
  "appTitle": "My App",
  "welcome": "Welcome, {name}!",
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}"
}

flutter:
  generate: true # 启用 gen-l10n

  l10n:
    arb-dir: lib/l10n          # ARB 文件目录
    template-arb-file: app_zh.arb
    output-localization-file: app_localizations.dart
    output-class: AppLocalizations
    nullable-getter: false

// 在 build 中获取本地化实例
AppLocalizations l10n = AppLocalizations.of(context)!;

Text(l10n.appTitle),                    // "我的应用"
Text(l10n.welcome('张三')),              // "欢迎，张三！"
Text(l10n.itemCount(3)),                // "3 个项目"

import 'package:intl/intl.dart';

final zhDate = DateFormat.yMMMd('zh').format(DateTime.now());
// 例如 2026年9月26日

final enDate = DateFormat.yMMMd('en').format(DateTime.now());
// 例如 Sep 26, 2026

// 自定义格式
final custom = DateFormat('yyyy-MM-dd HH:mm').format(DateTime.now());
// 2026-09-26 10:00

final nf = NumberFormat('#,##0.00', 'en_US');
print(nf.format(1234567.891)); // 1,234,567.89

// 货币：按地区自动带符号与小数位
final usd = NumberFormat.currency(locale: 'en_US', symbol: r'$');
print(usd.format(19.99)); // $19.99

final cny = NumberFormat.currency(locale: 'zh', symbol: '¥');
print(cny.format(19.99)); // ¥19.99

final euro = NumberFormat.currency(locale: 'de', name: 'EUR');
print(euro.format(19.99)); // 19,99 €（注意小数逗号）

// 语言切换为阿拉伯语后，Row/Column 的方向会自动翻转
Row(
  children: [
    Icon(Icons.arrow_back), // 在 RTL 下自动镜像为向前
    Text('返回'),
  ],
)

// 手动指定方向
Directionality(
  textDirection: TextDirection.rtl,
  child: Row(children: [...]), // 强制 RTL
)

// 用逻辑方向而非物理方向
Padding(
  padding: const EdgeInsetsDirectional.only(
    start: 16,  // RTL 下自动成为右侧
    end: 8,
  ),
  child: Row(
    children: [
      // Row 的 children 顺序在 RTL 下自动反转
      Text('标签'),
      const Spacer(),
      Text('值'),
    ],
  ),
)

class LocaleController extends ChangeNotifier {
  Locale _locale = const Locale('zh', 'CN');
  Locale get locale => _locale;

  Future<void> setLocale(Locale locale) async {
    _locale = locale;
    notifyListeners();
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString('locale', locale.toString()); // 持久化
  }
}

// 在 MaterialApp 中绑定
ListenableBuilder(
  listenable: localeController,
  builder: (context, _) => MaterialApp(
    locale: localeController.locale,
    supportedLocales: const [Locale('zh', 'CN'), Locale('en')],
    // ...delegates
  ),
)

DropdownButton<Locale>(
  value: currentLocale,
  items: const [
    DropdownMenuItem(value: Locale('zh', 'CN'), child: Text('简体中文')),
    DropdownMenuItem(value: Locale('en'), child: Text('English')),
    DropdownMenuItem(value: Locale('ja'), child: Text('日本語')),
  ],
  onChanged: (locale) => context.read<LocaleController>().setLocale(locale!),
)

# .vscode/settings.json（示例）
{
  "flutter-intl.arbDir": "lib/l10n",
  "flutter-intl.outputDir": "lib/l10n",
  "flutter-intl.enabled": true
}

// 好的做法：把文案集中调用，避免字符串散落
class AppStrings {
  static String appTitle(BuildContext context) =>
      AppLocalizations.of(context)!.appTitle;
}

import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_localizations/flutter_localizations.dart';

void main() {
  testWidgets('英文环境渲染正确', (tester) async {
    await tester.pumpWidget(
      MaterialApp(
        locale: const Locale('en'),
        supportedLocales: const [Locale('en')],
        localizationsDelegates: GlobalMaterialLocalizations.delegates,
        home: const HomePage(),
      ),
    );
    expect(find.text('My App'), findsOneWidget);
  });
}