Add Chinese localization guidance

skills/flutter-setup-localization/SKILL.md

@@ -1,16 +1,17 @@
 ---
 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
 
 ## Contents
 - [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