Flutter 官方國際化方案簡述詳情 - flutter,Dart,國際化,Android,移動開發 Datcon 博客

好的！以下是一篇基於你提供的簡書文章（原文鏈接）整理而成的技術博客。我保留了原文的核心流程、配置説明和全部代碼，並進行了結構優化、語言潤色與細節補充，使其更清晰、完整且適合開發者直接上手使用。

Flutter 官方國際化方案詳解：基於 ARB 文件的全自動代碼生成

作者：Qwen
參考來源：簡書《Flutter自帶國際化適配自動生成方案》

在 Flutter 開發中，支持多語言（國際化，i18n）是面向全球用户的基本需求。雖然社區有 flutter_localizations、easy_localization 等方案，但 Flutter 官方其實早已內置了一套成熟、高效、無需額外依賴的國際化生成機制 —— 只需編寫 .arb 文件，即可自動生成 Dart 代碼！

本文將手把手帶你配置並使用這套官方方案，實現真正的“寫配置即生效”。

一、整體流程概覽

Flutter 的官方國際化方案基於 ARB（Application Resource Bundle） 格式，配合 gen_l10n 工具鏈，實現以下自動化流程：

app_en.arb + app_zh.arb → flutter pub get → 自動生成 app_localizations.dart → 直接在代碼中調用

整個過程無需手動維護字符串映射，也無需第三方插件，完全由 Flutter SDK 原生支持。

二、詳細配置步驟

步驟 1：創建 `l10n.yaml` 配置文件

在項目根目錄下新建文件 l10n.yaml，內容如下：

arb-dir: lib/l10n/arb          # ARB 文件存放目錄
template-arb-file: app_en.arb  # 默認模板文件（通常為英文）
output-localization-file: app_localizations.dart  # 生成的 Dart 文件名
nullable-getter: false         # 是否允許返回 null（建議設為 false）

✅ 這個文件告訴 Flutter 工具鏈：去哪裏找資源、以哪個文件為基準、生成什麼代碼。

步驟 2：創建 ARB 文件與輔助 Dart 文件

2.1 創建目錄結構

lib/
└── l10n/
    ├── arb/
    │   ├── app_en.arb
    │   └── app_zh.arb
    └── l10n.dart

2.2 編寫 ARB 文件

lib/l10n/arb/app_en.arb（英文）：

{
  "@@locale": "en",
  "appName": "Remarks",
  "@appName": {
    "description": "應用名稱"
  }
}

lib/l10n/arb/app_zh.arb（中文）：

{
  "@@locale": "zh",
  "appName": "備註",
  "@appName": {
    "description": "應用名稱"
  }
}

📌 説明：

"@@locale" 指定語言代碼。

"key": "value" 是實際翻譯內容。

"@key" 是可選元數據，如 description（用於註釋）、placeholders（用於帶參數的字符串）等。

2.3 創建 `l10n.dart` 輔助擴展

lib/l10n/l10n.dart：

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

// 導出生成的類，方便全局 import
export 'package:flutter_gen/gen_l10n/app_localizations.dart';

// 擴展 BuildContext，提供便捷訪問方式
extension AppLocalizationsX on BuildContext {
  AppLocalizations get l10n => AppLocalizations.of(this)!;
}

⚠️ 初次編寫時，flutter_gen/gen_l10n/... 路徑會報紅（因為代碼尚未生成），這是正常的，下一步執行 pub get 後即可解決。

步驟 3：修改 `pubspec.yaml`

在 flutter 節點下添加 generate: true：

flutter:
  uses-material-design: true
  generate: true  # 👈 啓用本地化代碼生成

🔑 這是關鍵！沒有這一行，Flutter 不會觸發 ARB 到 Dart 的轉換。

步驟 4：運行依賴獲取命令

在終端執行：

flutter pub get

成功後，你會在項目隱藏目錄 .dart_tool/flutter_gen/gen_l10n/ 下看到自動生成的 app_localizations.dart 文件。

此時回到 l10n.dart，所有導入錯誤都會消失。

三、在應用中使用國際化

1. 配置 `MaterialApp`

確保你的 MaterialApp 啓用了本地化支持：

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'l10n/l10n.dart'; // 導入我們自己的 l10n.dart

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter I18n Demo',
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: HomePage(),
    );
  }
}

✅ AppLocalizations.localizationsDelegates 和 supportedLocales 是自動生成的靜態字段，包含所有語言支持。

2. 在頁面中調用翻譯文本

使用我們定義的 BuildContext 擴展：

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(context.l10n.appName), // 👈 直接調用
      ),
      body: Center(
        child: Text('Hello, ${context.l10n.appName}!'),
      ),
    );
  }
}

系統會根據設備語言自動選擇 app_en.arb 或 app_zh.arb 中的內容。

四、高級用法：帶參數的翻譯

ARB 支持佔位符，適用於動態內容。

app_en.arb：

{
  "welcomeMessage": "Hello, {name}!",
  "@welcomeMessage": {
    "description": "歡迎語",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "Alice"
      }
    }
  }
}

app_zh.arb：

{
  "welcomeMessage": "你好，{name}！"
}

Dart 中調用：

Text(context.l10n.welcomeMessage('張三'))

生成的 Dart 方法簽名會是：

String welcomeMessage(String name);

五、常見問題與注意事項

生成失敗？
檢查 l10n.yaml 路徑是否正確，pubspec.yaml 是否包含 generate: true，並確保 ARB 文件語法合法（可用 JSON 校驗工具檢查）。
新增語言？
只需在 arb/ 目錄下添加 app_xx.arb（如 app_fr.arb），重新 flutter pub get 即可。
熱重載不生效？
修改 ARB 文件後，需重啓應用（Hot Restart），因為本地化委託是在 MaterialApp 初始化時註冊的。
不支持的語言？
確保 supportedLocales 包含該語言。若自動生成未包含，可手動指定：

supportedLocales: [
  Locale('en'),
  Locale('zh'),
  Locale('fr'), // 手動添加
],

六、總結

Flutter 官方的 ARB 國際化方案具有以下優勢：

✅ 零依賴：無需引入第三方包。
✅ 自動化：寫 ARB 即生成 Dart 代碼。
✅ 類型安全：所有 key 都是方法，IDE 自動補全。
✅ 支持參數：通過 placeholders 實現動態文本。
✅ 符合標準：ARB 是 Google 推薦的國際化格式。

只需 5 步配置，即可讓你的 Flutter 應用輕鬆支持多語言，強烈推薦在新項目中採用！

📚 延伸閲讀

Flutter 官方文檔：Internationalization

ARB 格式規範

希望這篇指南能幫你快速上手 Flutter 官方國際化！歡迎點贊、收藏，或在評論區分享你的實踐經驗～

Datcon 博客

Datcon 博客

博客 / 詳情