diff --git a/skills/flutter-setup-localization/SKILL.md b/skills/flutter-setup-localization/SKILL.md index d3dd459..12ca62a 100644 --- a/skills/flutter-setup-localization/SKILL.md +++ b/skills/flutter-setup-localization/SKILL.md @@ -1,9 +1,9 @@ --- name: flutter-setup-localization -description: Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project. +description: Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, create an `l10n.yaml` configuration file, and add English/Chinese ARB files. Use when initializing localization support for a new Flutter project, especially when Chinese localization is required. metadata: model: models/gemini-3.1-pro-preview - last_modified: Tue, 21 Apr 2026 21:27:35 GMT + last_modified: Tue, 26 May 2026 00:00:00 GMT --- # Internationalizing Flutter Applications @@ -11,6 +11,7 @@ metadata: - [Core Concepts](#core-concepts) - [Setup Workflow](#setup-workflow) - [Implementation Workflow](#implementation-workflow) +- [Chinese Localization](#chinese-localization) - [Advanced Formatting](#advanced-formatting) - [Examples](#examples) @@ -25,7 +26,8 @@ Copy and track this checklist when initializing internationalization in a Flutte - [ ] 1. Add dependencies to `pubspec.yaml`. - [ ] 2. Enable the `generate` flag. - [ ] 3. Create the `l10n.yaml` configuration file. - - [ ] 4. Configure `MaterialApp` or `CupertinoApp`. + - [ ] 4. Create English and Chinese ARB files. + - [ ] 5. Configure `MaterialApp` or `CupertinoApp`. ### 1. Add Dependencies Add the required localization packages to the project. Execute the following commands in the terminal: @@ -60,7 +62,34 @@ output-localization-file: app_localizations.dart synthetic-package: true ``` -### 4. Configure the App Entry Point +### 4. Create English and Chinese ARB Files +Create the ARB directory and the initial template/localized files: + +```text +lib/l10n/app_en.arb +lib/l10n/app_zh.arb +``` + +Use English as the template locale and Chinese as the first localized locale: + +```json +{ + "helloWorld": "Hello World!", + "@helloWorld": { + "description": "The conventional newborn programmer greeting" + } +} +``` + +```json +{ + "helloWorld": "你好,世界!" +} +``` + +Use `app_zh_CN.arb` instead of, or in addition to, `app_zh.arb` when the project specifically targets Simplified Chinese for mainland China. + +### 5. Configure the App Entry Point Import the generated localizations and the `flutter_localizations` library in your `main.dart`. Inject the delegates and supported locales into your `MaterialApp` or `CupertinoApp`. ```dart @@ -78,6 +107,8 @@ return MaterialApp( supportedLocales: const [ Locale('en'), // English Locale('es'), // Spanish + Locale('zh'), // Chinese + Locale('zh', 'CN'), // Simplified Chinese, China ], home: const MyHomePage(), ); @@ -107,6 +138,13 @@ Create corresponding files for other locales (e.g., `app_es.arb`): } ``` +Create a Chinese localization file when Chinese is required (for example, `lib/l10n/app_zh.arb` or `lib/l10n/app_zh_CN.arb`): +```json +{ + "helloWorld": "你好,世界!" +} +``` + ### 2. Generate Localization Classes Run the following command to trigger code generation: ```bash @@ -121,6 +159,46 @@ Access the localized strings in your widget tree using `AppLocalizations.of(cont Text(AppLocalizations.of(context)!.helloWorld) ``` +## Chinese Localization + +When adding Chinese support, prefer this practical workflow: + +- Add `lib/l10n/app_zh.arb` for generic Chinese when the app does not need regional variants. +- Add `lib/l10n/app_zh_CN.arb` for Simplified Chinese in mainland China when regional behavior matters. +- If both files exist, keep `app_zh.arb` as the broad fallback and put region-specific wording in `app_zh_CN.arb`. +- Add `Locale('zh')` and, when needed, `Locale('zh', 'CN')` to `supportedLocales`. +- Keep every non-metadata key from the template ARB file present in the Chinese ARB file. + +Example `lib/l10n/app_en.arb`: +```json +{ + "appTitle": "Demo App", + "@appTitle": { + "description": "The application title" + }, + "helloUser": "Hello {userName}", + "@helloUser": { + "description": "Greeting shown on the home page", + "placeholders": { + "userName": { + "type": "String", + "example": "Alex" + } + } + } +} +``` + +Example `lib/l10n/app_zh.arb`: +```json +{ + "appTitle": "演示应用", + "helloUser": "你好,{userName}" +} +``` + +For Chinese text, check the UI after translation. Chinese strings may be shorter than English in some places and longer in others. Avoid hard-coded widths around localized labels unless the surrounding layout already handles overflow. + ## Advanced Formatting Use placeholders for dynamic data, plurals, and conditional selects. @@ -155,6 +233,11 @@ Use the `plural` syntax to handle quantity-based string variations. The `other` } ``` +Chinese commonly does not change nouns by count. It is still valid to keep a plural message for API consistency: +```json +"messageCount": "{count, plural, =0{没有消息} other{{count} 条消息}}" +``` + ### Selects Use the `select` syntax for conditional strings, such as gendered text. ```json