Localization

Relevant source files

This document describes the localization system implemented in the Flutter Mobile Project Template. It covers how internationalization is structured, configured, and used throughout the application and its feature packages.

Overview of the Localization System

The project implements a modular localization approach that follows Flutter's internationalization patterns. It uses ARB (Application Resource Bundle) files to define translations and the flutter_localizations package to generate Dart code from these files. The current implementation supports Japanese (ja) and English (en) languages by default.

Sources: packages/features/setting/l10n.yaml apps/app/l10n.yaml packages/features/setting/lib/src/gen/l10n/l10n.dart

Localization Architecture

A key feature of the template's localization approach is its modularity. Each feature package can have its own localization resources, separate from the main application. This allows features to be self-contained with their translations.

Sources: apps/app/lib/l10n/app_en.arb apps/app/lib/l10n/app_ja.arb packages/features/setting/lib/src/l10n/features_setting_en.arb packages/features/setting/lib/src/l10n/features_setting_ja.arb packages/features/setting/lib/src/gen/l10n/l10n.dart

Localization Configuration

Each module with localization support includes a l10n.yaml configuration file that defines how the localization is generated.

The typical configuration looks like this:

Configuration Key	Value	Description
arb-dir	lib/src/l10n	Directory containing ARB files
output-dir	lib/src/gen/l10n	Directory where generated files are placed
template-arb-file	features_setting_ja.arb	Template ARB file (usually Japanese)
output-localization-file	l10n.dart	Name of the main output file
output-class	L10n	Name of the output class
synthetic-package	false	Whether to generate a synthetic package
preferred-supported-locales	ja, en	Priority order of supported locales
nullable-getter	false	Whether getters can be null
format	true	Whether to format generated code

Sources: packages/features/setting/l10n.yaml apps/app/l10n.yaml packages/features/maintain/l10n.yaml

ARB File Structure

ARB files are JSON files that define localized strings. Each ARB file represents a single language and contains key-value pairs for the translations.

Example from the settings feature's Japanese ARB file:

{
  "@@locale": "ja",
  "settingAppBar": "設定",
  "settingThemeSetting": "テーマ設定",
  "settingAbout": "FlutterMobileTemplate について",
  "settingOpenSourceLicenses": "オープンソースライセンス",
  "settingLibrariesWeUse": "使用しているライブラリ",
  "settingVersion": "バージョン"
}

Sources: packages/features/setting/lib/src/l10n/features_setting_ja.arb packages/features/setting/lib/src/l10n/features_setting_en.arb

Generated Files

The Flutter gen-l10n tool generates several files based on the ARB files:

l10n.dart: Abstract base class with the string getters
l10n_en.dart: English implementation
l10n_ja.dart: Japanese implementation

The generated code includes:

Abstract class defining all string getters
Concrete implementations for each language
Helper methods for accessing the localizations
Localization delegates for Flutter's localization system

Sources: packages/features/setting/lib/src/gen/l10n/l10n.dart packages/features/setting/lib/src/gen/l10n/l10n_en.dart packages/features/setting/lib/src/gen/l10n/l10n_ja.dart

Using Localized Strings

To use the localized strings in your code:

Access the localization instance using the static of method:

final l10n = L10n.of(context);

Use the string getters:

Text(l10n.settingAppBar)

The MaterialApp must be configured with the localization delegates and supported locales:

MaterialApp(
  localizationsDelegates: L10n.localizationsDelegates,
  supportedLocales: L10n.supportedLocales,
  // ...
)

Sources: packages/features/setting/lib/src/gen/l10n/l10n.dart70-72 packages/features/setting/lib/src/gen/l10n/l10n.dart86-98

Adding New Languages

To add a new language to the project:

Create a new ARB file for each module that needs localization
- For app: lib/l10n/app_<language_code>.arb
- For features: lib/src/l10n/features_<feature_name>_<language_code>.arb
Add the language code to the preferred-supported-locales list in the l10n.yaml files
Run the Flutter gen-l10n tool to regenerate the localization files:
```
flutter gen-l10n
```

Adding New Localized Strings

To add new localized strings:

Add the new string to all ARB files for all languages
Run the Flutter gen-l10n tool to regenerate the localization files

Localization in Feature Packages

Each feature package can have its own localization resources. The template includes a brick template for creating new feature packages with localization support:

Sources: tools/bricks/features_package_core/__brick__/packages/features/{{feature_name.snakeCase()}}/l10n.yaml

The brick template automatically creates:

A configured l10n.yaml file
Directory structure for ARB files
Initial ARB files for Japanese and English

Integration with the App

When using multiple localization sources, each feature package's localization delegates need to be added to the main app's MaterialApp. This is typically done by adding each delegate to a combined list:

MaterialApp(
  localizationsDelegates: [
    // App's own localizations
    AppL10n.delegate,
    // Feature package localizations
    SettingL10n.delegate,
    MaintainL10n.delegate,
    // Default Flutter localizations
    GlobalMaterialLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
  ],
  supportedLocales: AppL10n.supportedLocales,
  // ...
)

Each feature package's L10n class has a static delegate property and supportedLocales list that can be used for this purpose.

Summary

The template's localization system provides:

Modular, feature-specific localization
Support for multiple languages (Japanese and English by default)
Easy expansion to additional languages
Clean separation of translations by feature
Generated code with type-safe access to localized strings

This approach enables efficient internationalization while maintaining the modular structure of the application.