Internationalizing Flutter Applications with flutter_localizations and ARB Files

Preparing an app for global audiences requires localizing UI strings, date formats, currency formats, and right-to-left (RTL) text orientation. Flutter provides first-party internationalization support via flutter_localizations and the gen-l10n tool built directly into the Flutter CLI.

Step 1: Configuring Dependencies and l10n.yaml

Add flutter_localizations to pubspec.yaml and set generate: true:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: ^0.19.0

flutter:
  generate: true # Enables automatic code generation for l10n

Next, create a file named l10n.yaml in your project root directory:

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

Step 2: Defining Application Resource Bundle (.arb) Files

Create translation files in lib/l10n/ using the .arb format (which is valid JSON extended with metadata attributes).

lib/l10n/app_en.arb:

{
  "@@locale": "en",
  "appTitle": "RedLineSoft Blog",
  "@appTitle": {
    "description": "The title of the blog application"
  },
  "welcomeUser": "Welcome back, {username}!",
  "@welcomeUser": {
    "description": "Greeting message with username placeholder",
    "placeholders": {
      "username": {
        "type": "String"
      }
    }
  },
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "description": "Pluralized item message",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

lib/l10n/app_th.arb (Thai translation):

{
  "@@locale": "th",
  "appTitle": "เรดไลน์ซอฟต์ บล็อก",
  "welcomeUser": "ยินดีต้อนรับกลับมาคุณ {username}!",
  "itemCount": "{count, plural, =0{ไม่มีรายการ} other{{count} รายการ}}"
}

Step 3: Registering Localizations in MaterialApp

Run flutter pub get or build the app to automatically trigger gen-l10n. Then import AppLocalizations in your entrypoint:

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

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Localizable App',
      localizationsDelegates: const [
        AppLocalizations.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: const [
        Locale('en'), // English
        Locale('th'), // Thai
      ],
      home: const HomeScreen(),
    );
  }
}

Step 4: Accessing Localized Strings in Widgets

Use AppLocalizations.of(context) to access type-safe, auto-generated methods:

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

  @override
  Widget build(BuildContext context) {
    final l10n = AppLocalizations.of(context)!;

    return Scaffold(
      appBar: AppBar(
        title: Text(l10n.appTitle),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              l10n.welcomeUser('Alex'),
              style: Theme.of(context).textTheme.headlineSmall,
            ),
            const SizedBox(height: 12),
            Text(
              l10n.itemCount(5),
              style: Theme.of(context).textTheme.bodyMedium,
            ),
          ],
        ),
      ),
    );
  }
}

Dynamic Locale Switching

To switch locales dynamically at runtime, pass the chosen Locale into MaterialApp’s locale parameter via your state management solution (such as Riverpod, Bloc, or Provider).

Takeaway: Combining flutter_localizations, .arb templates, and gen-l10n delivers type-safe, maintainable multi-language and pluralization support for Flutter apps.