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=flutterflutter 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/l10ntemplate-arb-file: app_en.arboutput-localization-file: app_localizations.dartsynthetic-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 methodreturn 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/l10ntemplate-arb-file: app_en.arboutput-localization-file: app_localizations.dartsynthetic-package: trueuse-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)),      ],    );  }}