Localizing Flutter Applications Contents Core Configuration Defining ARB Resources App Integration Advanced Formatting Workflows Troubleshooting & Gotchas Core Configuration Configure the project to support code generation for localizations. Add required dependencies to pubspec.yaml : dependencies : flutter : sdk : flutter flutter_localizations : sdk : flutter intl : any flutter : generate : true

Required for l10n code generation

Create an l10n.yaml file in the project root to configure the gen-l10n tool: arb-dir : lib/l10n template-arb-file : app_en.arb output-localization-file : app_localizations.dart

Optional: Set to false to generate files into lib/ instead of the synthetic package

synthetic-package: false

Defining ARB Resources Store localized strings in Application Resource Bundle ( .arb ) files within the configured arb-dir . Create the template file (e.g., lib/l10n/app_en.arb ): { "helloWorld" : "Hello World!" , "@helloWorld" : { "description" : "The conventional newborn programmer greeting" } } Create translation files (e.g., lib/l10n/app_es.arb ): { "helloWorld" : "¡Hola Mundo!" } App Integration Initialize the Localizations widget by configuring the root MaterialApp or CupertinoApp . import 'package:flutter_localizations/flutter_localizations.dart' ; import 'package:flutter_gen/gen_l10n/app_localizations.dart' ; // Adjust import if synthetic-package is false return MaterialApp ( title : 'Localized App' , localizationsDelegates : const [ AppLocalizations . delegate , GlobalMaterialLocalizations . delegate , GlobalWidgetsLocalizations . delegate , GlobalCupertinoLocalizations . delegate , ] , supportedLocales : const [ Locale ( 'en' ) , // English Locale ( 'es' ) , // Spanish ] , home : const MyHomePage ( ) , ) ; Access localized values in the widget tree using the generated AppLocalizations class: Text ( AppLocalizations . of ( context ) ! . helloWorld ) Note: If using WidgetsApp instead of MaterialApp , omit GlobalMaterialLocalizations.delegate . Advanced Formatting Use placeholders, plurals, and selects for dynamic content. Define parameters in the @key metadata. Placeholders "hello" : "Hello {userName}" , "@hello" : { "description" : "A message with a single parameter" , "placeholders" : { "userName" : { "type" : "String" , "example" : "Bob" } } } Plurals "nWombats" : "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}" , "@nWombats" : { "placeholders" : { "count" : { "type" : "num" , "format" : "compact" } } } Selects (Gender/Enums) "pronoun" : "{gender, select, male{he} female{she} other{they}}" , "@pronoun" : { "placeholders" : { "gender" : { "type" : "String" } } } Dates and Numbers Use format and optionalParameters to leverage intl formatting. "dateMessage" : "Date: {date}" , "@dateMessage" : { "placeholders" : { "date" : { "type" : "DateTime" , "format" : "yMd" } } } Workflows Task Progress: Adding a New Language Copy this checklist to track progress when introducing a new locale. Create a new .arb file in the arb-dir (e.g., app_fr.arb ). Translate all keys present in the template .arb file. Add the new Locale to the supportedLocales list in MaterialApp . Run validator -> Execute flutter gen-l10n to verify ARB syntax and regenerate AppLocalizations . Review errors -> Fix any missing placeholders or malformed plural/select statements. If targeting iOS, complete the "Configuring iOS App Bundle" workflow. Task Progress: Configuring iOS App Bundle Flutter handles runtime localization, but iOS requires bundle-level configuration for the App Store and system settings. Open ios/Runner.xcodeproj in Xcode. Select the Runner project in the Project Navigator. Navigate to the Info tab. Under the Localizations section, click the + button. Add the newly supported languages/regions. Run validator -> Build the iOS app to ensure project.pbxproj is correctly updated. Troubleshooting & Gotchas Missing Localizations Ancestor Widgets like TextField and CupertinoTabBar require a Localizations ancestor with specific delegates ( MaterialLocalizations or CupertinoLocalizations ). Error: No MaterialLocalizations found. or CupertinoTabBar requires a Localizations parent... Fix: Ensure the widget is a descendant of MaterialApp / CupertinoApp . If building a standalone widget tree (e.g., in tests or a custom WidgetsApp ), wrap the widget in a Localizations widget: Localizations ( locale : const Locale ( 'en' , 'US' ) , delegates : const [ DefaultWidgetsLocalizations . delegate , DefaultMaterialLocalizations . delegate , // Required for TextField DefaultCupertinoLocalizations . delegate , // Required for CupertinoTabBar ] , child : child , ) Advanced Locale Definition If supporting languages with multiple scripts (e.g., Chinese), use Locale.fromSubtags to explicitly define the scriptCode and countryCode to prevent Flutter from resolving to an unexpected variant. supportedLocales : const [ Locale . fromSubtags ( languageCode : 'zh' , scriptCode : 'Hans' , countryCode : 'CN' ) , Locale . fromSubtags ( languageCode : 'zh' , scriptCode : 'Hant' , countryCode : 'TW' ) , ]