Flutter 應用程式國際化
目錄
核心概念
Flutter 透過 flutter_localizations 和 intl 套件處理國際化 (i18n) 與在地化 (l10n)。標準方法是使用 App Resource Bundle (.arb) 檔案定義在地化字串,然後編譯成產生的 AppLocalizations 類別,以便在 widget 樹中進行型別安全的存取。
設定工作流程
在 Flutter 專案初始化國際化時,請複製並追蹤這份核對清單:
- 任務進度
- 1. 在
pubspec.yaml中新增相依套件。 - 2. 啟用
generate標記。 - 3. 建立
l10n.yaml設定檔。 - 4. 設定
MaterialApp或CupertinoApp。
- 1. 在
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'; // 若 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) 中。加入描述以提供上下文。 - 若為編輯既有內容: 在所有支援的
.arb檔案中找到對應的鍵,並更新其值。
{
"helloWorld": "Hello World!",
"@helloWorld": {
"description": "新手程式設計師的傳統問候"
}
}
為其他語系建立對應的檔案(例如 app_es.arb):
{
"helloWorld": "¡Hola Mundo!"
}
2. 產生在地化類別
執行下列指令以觸發程式碼產生:
flutter pub get
回饋迴圈: 執行驗證器 -> 檢視終端機輸出是否有 ARB 語法錯誤 -> 修正遺漏的逗號或不相符的佔位符 -> 重新執行 flutter pub get。
3. 使用在地化字串
使用 AppLocalizations.of(context) 在 widget 樹中存取在地化字串。請確認呼叫此方法的 widget 是 MaterialApp 的子代。
Text(AppLocalizations.of(context)!.helloWorld)
進階格式化
使用佔位符處理動態資料、複數形式以及條件選取。
佔位符
在大括號內定義參數,並在中繼資料物件中指定其型別。
"hello": "Hello {userName}",
"@hello": {
"description": "一個包含單一參數的訊息",
"placeholders": {
"userName": {
"type": "String",
"example": "Bob"
}
}
}
複數形式
使用 plural 語法處理根據數量變化的字串。other 情況是必需的。
"nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
"@nWombats": {
"description": "一個複數訊息",
"placeholders": {
"count": {
"type": "num",
"format": "compact"
}
}
}
條件選取
使用 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)),
],
);
}
}