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:

bashCopy code
flutter pub add flutter_localizations --sdk=flutter
flutter pub add intl:any

Verify your pubspec.yaml includes the following under dependencies:

yamlCopy code
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:

yamlCopy code
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:

yamlCopy code
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.

dartCopy code
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.

jsonCopy code
{
  "helloWorld": "Hello World!",
  "@helloWorld": {
    "description": "The conventional newborn programmer greeting"
  }
}

Create corresponding files for other locales (e.g., app_es.arb):

jsonCopy code
{
  "helloWorld": "¡Hola Mundo!"
}

2. Generate Localization Classes

Run the following command to trigger code generation:

bashCopy code
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.

dartCopy code
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.

jsonCopy code
"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.

jsonCopy code
"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.

jsonCopy code
"pronoun": "{gender, select, male{he} female{she} other{they}}",
"@pronoun": {
  "description": "A gendered message",
  "placeholders": {
    "gender": {
      "type": "String"
    }
  }
}

Examples

Complete l10n.yaml

yamlCopy code
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

dartCopy code
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)),
      ],
    );
  }
}