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 檔案中找到對應的鍵，並更新其值。

{
  "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)),
      ],
    );
  }
}