flutter-setup-localization

Internationalizing Flutter Applications Contents Core Concepts Setup Workflow Implementation Workflow Advanced Formatting Examples Core Concepts Flutter handles internationalization (i18n) and localization (l10n) via the flutter_localizations and intl packages. The standard approach uses App Resource Bundle ( .arb ) files to define localized strings, which are then compiled into a generated AppLocalizations class for type-safe access within the widget tree. Setup Workflow Copy and track this checklist when initializing internationalization in a Flutter project: Task Progress 1. Add dependencies to pubspec.yaml . 2. Enable the generate flag. 3. Create the l10n.yaml configuration file. 4. Configure MaterialApp or CupertinoApp . 1. Add Dependencies Add the required localization packages to the project. Execute the following commands in the terminal: flutter pub add flutter_localizations --sdk = flutter flutter pub add intl:any Verify your pubspec.yaml includes the following under dependencies : dependencies : flutter : sdk : flutter flutter_localizations : sdk : flutter intl : any 2. Enable Code Generation Open pubspec.yaml and enable the generate flag within the flutter section to automate localization tasks: flutter : generate : true 3. Create Configuration File Create a new file named l10n.yaml in the root directory of the Flutter project. Define the input directory, template file, and output file: arb-dir : lib/l10n template-arb-file : app_en.arb output-localization-file : app_localizations.dart synthetic-package : true 4. 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 . import 'package:flutter_localizations/flutter_localizations.dart' ; import 'package:flutter_gen/gen_l10n/app_localizations.dart' ; // Adjust path if synthetic-package is false // ... inside build method return MaterialApp ( localizationsDelegates : const [ AppLocalizations . delegate , GlobalMaterialLocalizations . delegate , GlobalWidgetsLocalizations . delegate , GlobalCupertinoLocalizations . delegate , ] , supportedLocales : const [ Locale ( 'en' ) , // English Locale ( 'es' ) , // Spanish ] , home : const MyHomePage ( ) , ) ; Implementation Workflow Follow this workflow when adding or modifying localized content. 1. Define ARB Files If creating NEW content: Add the base string to the template file ( lib/l10n/app_en.arb ). Include a description for context. If EDITING existing content: Locate the key in all supported .arb files and update the values. { "helloWorld" : "Hello World!" , "@helloWorld" : { "description" : "The conventional newborn programmer greeting" } } Create corresponding files for other locales (e.g., app_es.arb ): { "helloWorld" : "¡Hola Mundo!" } 2. Generate Localization Classes Run the following command to trigger code generation: flutter pub get Feedback Loop: Run validator -> review terminal output for ARB syntax errors -> fix missing commas or mismatched placeholders -> re-run flutter pub get . 3. Consume Localized Strings Access the localized strings in your widget tree using AppLocalizations.of(context) . Ensure the widget calling this is a descendant of MaterialApp . Text ( AppLocalizations . of ( context ) ! . helloWorld ) Advanced Formatting Use placeholders for dynamic data, plurals, and conditional selects. Placeholders Define parameters within curly braces and specify their type in the metadata object. "hello" : "Hello {userName}" , "@hello" : { "description" : "A message with a single parameter" , "placeholders" : { "userName" : { "type" : "String" , "example" : "Bob" } } } Plurals Use the plural syntax to handle quantity-based string variations. The other case is mandatory. "nWombats" : "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}" , "@nWombats" : { "description" : "A plural message" , "placeholders" : { "count" : { "type" : "num" , "format" : "compact" } } } Selects Use the select syntax for conditional strings, such as gendered text. "pronoun" : "{gender, select, male{he} female{she} other{they}}" , "@pronoun" : { "description" : "A gendered message" , "placeholders" : { "gender" : { "type" : "String" } } } Examples Complete l10n.yaml arb-dir : lib/l10n template-arb-file : app_en.arb output-localization-file : app_localizations.dart synthetic-package : true use-escaping : true Complete Widget Implementation import 'package:flutter/material.dart' ; import 'package:flutter_gen/gen_l10n/app_localizations.dart' ; class GreetingWidget extends StatelessWidget { final String userName ; final int notificationCount ; const GreetingWidget ( { super . key , required this . userName , required this . notificationCount , } ) ; @override Widget build ( BuildContext context ) { final l10n = AppLocalizations . of ( context ) ! ; return Column ( children : [ Text ( l10n . hello ( userName ) ) , Text ( l10n . nWombats ( notificationCount ) ) , ] , ) ; } }