Skip to content

Poorgramer-Zack/dart-expert-skills / skills/flutter-expert

building-flutter-production-apps

Verified

Expert-level guidance for Flutter production applications: architecture decisions (Clean/Layered/Hexagonal/Feature-First), advanced state management (BLoC/Riverpod/GetX), performance optimization (eliminating jank, memory profiling, reducing rebuild overhead), code review with design pattern enforcement, scalability assessments, native platform integration (MethodChannel/EventChannel/FFI), complex UI challenges (custom render objects, slivers), testing strategies (unit/widget/integration/golden), CI/CD pipeline architecture, build optimization, and accessibility compliance. Triggers: 'architecture decision', 'design pattern', 'performance issue', 'code review', 'production problem', 'scaling concerns', 'best practices', 'technical debt', 'refactoring strategy'. Essential for complex enterprise apps, critical production debugging, architectural refactors, or when choosing between competing technical approaches.

references/localization.md

View on GitHub
---
name: "flutter-localization"
description: "Configure your Flutter app to support different languages and regions"
metadata:
  last_modified: "2026-03-12 11:18:17 (GMT+8)"

---
# Flutter Localization Setup

## Goal
Configures and implements internationalization (i18n) and localization (l10n) in a Flutter application. This skill manages dependency injection (`flutter_localizations`, `intl`), code generation configuration (`l10n.yaml`), root widget setup (`MaterialApp`, `CupertinoApp`, or `WidgetsApp`), `.arb` translation file management, and platform-specific configurations (iOS Xcode project updates). It ensures proper locale resolution and prevents common assertion errors related to missing localization delegates in specific widgets like `TextField` and `CupertinoTabBar`.

## Decision Logic
1. **Determine App Root:** Identify if the application uses `MaterialApp`, `CupertinoApp`, or `WidgetsApp` to inject the correct global delegates.
2. **Identify Target Platforms:** If iOS is a target platform, Xcode project files (`Info.plist` / `project.pbxproj`) must be updated to expose supported locales to the App Store.
3. **Analyze Widget Tree:** Check for isolated `TextField` or `CupertinoTabBar` widgets that might exist outside the root app's localization scope. If found, wrap them in explicit `Localizations` widgets.
4. **Determine Locale Complexity:** If supporting languages with multiple scripts/regions (e.g., Chinese `zh_Hans_CN`), use `Locale.fromSubtags` instead of the default `Locale` constructor.

## Instructions

1. **Configure Dependencies**
   Update `pubspec.yaml` to include required packages and enable code generation.
   ```yaml
   dependencies:
     flutter:
       sdk: flutter
     flutter_localizations:
       sdk: flutter
     intl: any

   flutter:
     generate: true
   ```

2. **Configure Code Generation**
   Create an `l10n.yaml` file in the project root to define the localization tool's behavior.
   ```yaml
   arb-dir: lib/l10n
   template-arb-file: app_en.arb
   output-localization-file: app_localizations.dart
   ```
   Do not add `synthetic-package`. The option was removed: `true` fails the build, and `false` only prints a warning.

3. **Define Supported Locales**
   **STOP AND ASK THE USER:** "Which languages and regions do you want to support? Please provide a list of language codes (e.g., 'en', 'es', 'zh_Hans_CN')."

4. **Create ARB Files**
   Generate the template `.arb` file (e.g., `lib/l10n/app_en.arb`) and corresponding translation files. Implement placeholders, plurals, and selects as needed.
   ```json
   {
     "helloWorld": "Hello World!",
     "@helloWorld": {
       "description": "Standard greeting"
     },
     "greeting": "Hello {userName}",
     "@greeting": {
       "description": "Greeting with a parameter",
       "placeholders": {
         "userName": {
           "type": "String"
         }
       }
     },
     "nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
     "@nWombats": {
       "placeholders": {
         "count": {
           "type": "num",
           "format": "compact"
         }
       }
     }
   }
   ```

5. **Initialize Root App**
   Import the generated localizations file and configure the root `MaterialApp` or `CupertinoApp`.
   ```dart
   import 'package:flutter_localizations/flutter_localizations.dart';
   import 'package:your_app_name/l10n/app_localizations.dart'; // Adjust path based on synthetic-package setting

   // Inside your root widget build method:
   return MaterialApp(
     title: 'Localized App',
     localizationsDelegates: const [
       AppLocalizations.delegate,
       GlobalMaterialLocalizations.delegate,
       GlobalWidgetsLocalizations.delegate,
       GlobalCupertinoLocalizations.delegate,
     ],
     supportedLocales: const [
       Locale('en', ''), // English
       Locale('es', ''), // Spanish
       Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans', countryCode: 'CN'),
     ],
     home: const MyHomePage(),
   );
   ```

6. **Handle Isolated Widgets (If Applicable)**
   If a `TextField` or `CupertinoTabBar` throws a missing `MaterialLocalizations` or `Localizations` ancestor error, inject a `Localizations` widget directly above it.
   ```dart
   Localizations(
     locale: const Locale('en', 'US'),
     delegates: const <LocalizationsDelegate<dynamic>>[
       DefaultWidgetsLocalizations.delegate,
       DefaultMaterialLocalizations.delegate,
       DefaultCupertinoLocalizations.delegate,
     ],
     child: CupertinoTabBar(
       items: const <BottomNavigationBarItem>[...],
     ),
   )
   ```

7. **Configure iOS Project**
   **STOP AND ASK THE USER:** "Does this project target iOS? If yes, I will provide instructions for updating the Xcode project."
   If yes, instruct the user to:
   1. Open `ios/Runner.xcodeproj` in Xcode.
   2. Select the `Runner` project in the Project Navigator.
   3. Go to the `Info` tab.
   4. Under **Localizations**, click `+` to add all supported languages.

8. **Validate and Fix**
   Run `flutter gen-l10n`. Verify that `app_localizations.dart` is generated successfully. If compilation fails with "No MaterialLocalizations found" or "CupertinoTabBar requires a Localizations parent", traverse up the widget tree from the failing widget and ensure `localizationsDelegates` are properly provided.

## Constraints
* **No Synthetic Packages:** Since Flutter 3.32, generated l10n is written into the source tree. Use `synthetic-package: false` in `l10n.yaml`, keep `flutter: generate: true` in `pubspec.yaml` (required), and never import `package:flutter_gen`. Source: official guide `flutter-generate-i10n-source`.
* **Widget Requirements:** `TextField` MUST have a `MaterialLocalizations` ancestor. `CupertinoTabBar` MUST have a `Localizations` ancestor.
* **Complex Locales:** Always use `Locale.fromSubtags` for languages requiring script codes (e.g., Chinese `zh_Hans`, `zh_Hant`).
* **ARB Syntax:** Ensure all placeholders used in `.arb` strings are explicitly defined in the corresponding `@` metadata object.
* **Escaping:** If literal curly braces `{}` or single quotes `'` are needed in `.arb` files, enable `use-escaping: true` in `l10n.yaml` and use consecutive single quotes `''` for escaping.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall