How to Set Up Flutter Localization with flutter_localizations and intl

To set up Flutter localization, add the flutter_localizations and intl packages to your project, enable code generation in pubspec.yaml, configure the l10n.yaml build file, and import the generated AppLocalizations class into your app's localization delegates.

Flutter's internationalization (i18n) workflow relies on two core packages: flutter_localizations, which provides the SDK's localization delegates and generation infrastructure, and intl, which handles locale-aware formatting and pluralization logic. According to the official flutter/skills repository, specifically the skill file at skills/flutter-setup-localization/SKILL.md, this setup creates a type-safe AppLocalizations class that stays synchronized with your ARB translation files automatically.

Configure Dependencies and Code Generation

The first phase involves declaring dependencies and instructing the Flutter tool to generate localization code automatically.

Add Required Packages

You need both the Flutter SDK localization package and the Dart intl library. Run the following commands or update your pubspec.yaml directly:

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

Your pubspec.yaml should include these entries:

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

Enable Flutter Generation

To activate the automatic code generation that converts ARB files into Dart classes, add the generate flag under the flutter section in pubspec.yaml:

flutter:
  generate: true

This setting ensures the localization builder runs automatically after each flutter pub get or any Flutter command.

Set Up the Localization Toolkit

Once dependencies are configured, you must define where translation files live and how they should be processed.

Create the l10n.yaml Configuration

Create a file named l10n.yaml in your project root to configure the code generator:

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

This configuration tells the builder to:

• Look for ARB files in lib/l10n/
• Use app_en.arb as the template for type generation
• Output the generated class to the synthetic package flutter_gen/gen_l10n/app_localizations.dart

Define ARB Resource Files

Create the directory lib/l10n/ and add your Application Resource Bundle (ARB) files. Start with the template file app_en.arb containing default strings and metadata:

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

Add translation files for additional locales, such as app_es.arb for Spanish:

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

Generate and Integrate AppLocalizations

With configuration in place, generate the Dart code and wire it into your application widget tree.

Trigger Code Generation

Run the following command to generate the localization class:

flutter pub get

Because flutter.generate: true is enabled in pubspec.yaml, the tool automatically produces app_localizations.dart in the synthetic package. You do not need to manually edit generated files.

Wire Delegates into MaterialApp

Import the generated localizations and required delegates in your lib/main.dart or entry point file:

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';

Add the AppLocalizations.delegate along with the global delegates to your MaterialApp or CupertinoApp:

MaterialApp(
  localizationsDelegates: const [
    AppLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en'),
    Locale('es'),
  ],
  home: const MyHomePage(),
)

Access localized strings using AppLocalizations.of(context):

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    final l10n = AppLocalizations.of(context)!;
    return Scaffold(
      appBar: AppBar(title: Text(l10n.helloWorld)),
      body: const Center(child: Text('…')),
    );
  }
}

Handle Advanced Message Types

The ARB format supports placeholders, plurals, and select statements. Define these in your template ARB file with proper metadata:

{
  "hello": "Hello {userName}",
  "@hello": {
    "description": "A message with a single parameter",
    "placeholders": {
      "userName": {
        "type": "String",
        "example": "Bob"
      }
    }
  },
  "nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
  "@nWombats": {
    "description": "A plural message",
    "placeholders": {
      "count": {
        "type": "num",
        "format": "compact"
      }
    }
  }
}

Use these in Dart by passing the parameters directly:

Text(l10n.hello('Alice'));
Text(l10n.nWombats(notificationCount));

Summary

• Add dependencies: Include flutter_localizations (SDK) and intl in pubspec.yaml.
• Enable generation: Set flutter.generate: true to trigger automatic code generation.
• Configure builder: Create l10n.yaml specifying your arb-dir, template file, and output location.
• Define translations: Create ARB files in lib/l10n/ with metadata for type safety.
• Wire the app: Import flutter_gen/gen_l10n/app_localizations.dart and add AppLocalizations.delegate to your MaterialApp.localizationsDelegates.
• Access strings: Use AppLocalizations.of(context) to retrieve strongly-typed, localized messages.

Frequently Asked Questions

Where are the generated localization files located?

When synthetic-package: true is set in l10n.yaml (the default), Flutter generates the app_localizations.dart file in the synthetic package flutter_gen/gen_l10n/. You import this using import 'package:flutter_gen/gen_l10n/app_localizations.dart'; even though the directory does not exist in your source tree.

Why is flutter.generate: true required in pubspec.yaml?

The flutter.generate: true flag activates the Flutter tool's code generation hooks. Without this setting, the localization builder does not run automatically after flutter pub get, and the AppLocalizations class will not be created or updated when you modify ARB files.

Can I use Flutter localization without the intl package?

No. While flutter_localizations provides the delegates and generation infrastructure, the underlying locale-aware formatting, pluralization rules, and ICU message parsing rely on the intl package. The generated AppLocalizations class uses intl functions internally to handle complex message syntax.

How do I add support for a new language?

Create a new ARB file in your configured arb-dir (e.g., lib/l10n/app_fr.arb for French) containing the translated strings for that locale. Add the corresponding Locale to your MaterialApp.supportedLocales list, then run flutter pub get to regenerate the localizations class. The new locale becomes available immediately through AppLocalizations.of(context).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}