flutter-setup-localization

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. 新增相依套件

將所需的在地化套件新增至專案中。請在終端機執行以下命令：

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 檔案中找到該 key 並更新其數值。

{
  "helloWorld": "Hello World!",
  "@helloWorld": {
    "description": "程式新手慣用的問候語"
  }
}

為其他語系建立對應的檔案（例如 app_es.arb）：

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

2. 生成在地化類別

執行以下命令以觸發程式碼生成：

flutter pub get

回饋循環： 執行驗證器 -> 檢查終端機輸出的 ARB 語法錯誤 -> 修復遺漏的逗號或不匹配的佔位符 -> 重新執行 flutter pub get。

3. 使用在地化字串

在 Widget 樹中透過 AppLocalizations.of(context) 存取在地化字串。請確保呼叫此方法的 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)),
      ],
    );
  }
}