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

• Determine App Root: Identify if the application uses MaterialApp , CupertinoApp , or WidgetsApp to inject the correct global delegates.

• 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.

• 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.

• 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

Configure Dependencies Update pubspec.yaml to include required packages and enable code generation.

dependencies: flutter: sdk: flutter flutter_localizations: sdk: flutter intl: any

flutter: generate: true

Configure Code Generation Create an l10n.yaml file in the project root to define the localization tool's behavior.

arb-dir: lib/l10n template-arb-file: app_en.arb output-localization-file: app_localizations.dart synthetic-package: false

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')."

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.

{ "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" } } } }

Initialize Root App Import the generated localizations file and configure the root MaterialApp or CupertinoApp .

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(), );

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.

Localizations( locale: const Locale('en', 'US'), delegates: const <LocalizationsDelegate<dynamic>>[ DefaultWidgetsLocalizations.delegate, DefaultMaterialLocalizations.delegate, DefaultCupertinoLocalizations.delegate, ], child: CupertinoTabBar( items: const <BottomNavigationBarItem>[...], ), )

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:

• Open ios/Runner.xcodeproj in Xcode.

• Select the Runner project in the Project Navigator.

• Go to the Info tab.

• Under Localizations, click + to add all supported languages.

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: Ensure synthetic-package: false is considered if the user's environment requires direct source generation, or rely on standard generate: true behavior for modern Flutter versions. Do not use package:flutter_gen imports if synthetic-package: false is set.

• 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.