tool_locale 0.0.5

Contains common arch components for locale

tool_locale

Contains common architecture components for locale and localization management.

Adding Localization to a Module

This guide explains how to add Flutter localization support to any module (tool or feature) in the project.

Prerequisites

• Your module should extend BaseModule from tool_modularity
• Add dependencies to pubspec.yaml:

  dependencies:
    flutter_localizations:
      sdk: flutter
    intl: any
    tool_modularity:
    tool_utils:
  
  flutter:
    generate: true
  

Step-by-Step Guide

1. Create l10n configuration file

Create l10n.yaml in the root of your module:

arb-dir: lib/l10n/templates
template-arb-file: app_en.arb
output-localization-file: your_module_localization.dart
output-class: YourModuleLocalization
synthetic-package: false
output-dir: lib/l10n/generated

Important: Replace your_module and YourModule with your actual module name (e.g., tool_config → ToolConfigLocalization).

2. Add your module to Google Sheets and download ARB files

The project uses Google Sheets for centralized localization management.

a) Add your module to the localization spreadsheet:

1. Open the project's localization Google Sheet (spreadsheet ID is in scripts/generate/localization/download_localization.dart)
2. Create a new sheet with the name matching your module path (e.g., tools/tool_config, features/feature_auth)
3. Add your localization keys and translations in columns: name, en, ru, uk

b) Download ARB files:

From the project root, run:

melos run localization

Alternatively, for local development/testing, you can manually create ARB template files:

Create directory lib/l10n/templates/ and add ARB files for each supported language:

lib/l10n/templates/app_en.arb, app_ru.arb, app_uk.arb:

{
  "@@locale": "en",
  "name": "en",
  "exampleMessage": "This is an example message"
}

3. Generate localization files (if not already done)

If you ran melos run localization, the files are already generated. Otherwise, run:

fvm flutter gen-l10n

Or from project root for all modules with l10n.yaml:

melos run localization:generate

This generates files in lib/l10n/generated/:

• your_module_localization.dart - Base localization class
• your_module_localization_en.dart - English implementation
• your_module_localization_ru.dart - Russian implementation
• your_module_localization_uk.dart - Ukrainian implementation

4. Update your module class

a) Add LocalizationModule mixin to your module:

import 'package:tool_modularity/modularity.dart';
import 'package:your_module/l10n/generated/your_module_localization.dart';
import 'package:your_module/l10n/generated/your_module_localization_en.dart';
import 'package:flutter/widgets.dart';
import 'package:tool_utils/utils.dart';

abstract class YourModule extends BaseModule
    with LocalizationModule<YourModuleLocalization> {
  static final YourModule _instance = _YourModuleImpl();

  static YourModule get instance => _instance;
}

// BuildContext extension for easy access
extension YourModuleLocalizationExt on BuildContext {
  YourModuleLocalization get yourModuleLocalization =>
      YourModuleLocalization.of(this)!;
}

b) Implement required methods in your module implementation:

part of 'your_module.dart';

class _YourModuleImpl extends YourModule {
  @override
  LocalizationsDelegate get localizationsDelegate =>
      YourModuleLocalization.delegate;

  @override
  void onLocalizationUpdate(BuildContext context) {
    updateLocalization(context.yourModuleLocalization);
  }

  @override
  YourModuleLocalization lookupLocalizations({Locale? locale}) {
    return locale?.let(lookupYourModuleLocalization) ??
        YourModuleLocalizationEn();
  }

  @override
  Future<void> setupDependencies(GetIt getIt) async {
    // Your DI setup here
  }
}

5. Export generated localization files

Update your module's main export file (e.g., lib/your_module.dart or lib/config.dart):

// Localization
export 'l10n/generated/your_module_localization.dart';
export 'l10n/generated/your_module_localization_en.dart';
export 'l10n/generated/your_module_localization_ru.dart';
export 'l10n/generated/your_module_localization_uk.dart';

6. Register the module in your app

In your app's module list:

final modules = <BaseModule>[
  // ... other modules
  YourModule.instance,
];

The app's MaterialApp will automatically register the localization delegate.

Usage Examples

In Widgets (with BuildContext)

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final l10n = context.yourModuleLocalization;
    return Text(l10n.exampleMessage);
  }
}

In BLoC/Business Logic (without BuildContext)

class MyClass {
  String getErrorMessage() {
    final l10n = YourModule.instance.localization;
    return l10n.errorOccurred;
  }
}

In Error Handlers

class YourErrorHandlerProvider implements ErrorHandlerProvider {
  YourModuleLocalization get localizations =>
      YourModule.instance.localization;

  @override
  ErrorInfo? getError(Object error, [StackTrace? stacktrace]) {
    if (error is YourCustomException) {
      return ErrorInfo.message(
        localizations.errorOccurred,
        error,
        stackTrace: stacktrace,
      );
    }
    return null;
  }
}

Real-World Examples in Codebase

• tool_config: See tools/tool_config/ for a complete implementation
• feature_auth: See features/feature_auth/ for feature module example
• feature_base: See features/feature_base/ for base feature example

Tips

1. Centralized Management: Always add localization strings to the Google Sheets spreadsheet, not directly to ARB files
2. Naming Convention: Use clear, descriptive keys (e.g., featureNotSupported, not msg1)
3. Consistency: Keep the same keys across all language columns (en, ru, uk) in Google Sheets
4. Regeneration: Run melos run localization after updating Google Sheets
5. Git: Commit both ARB files and generated Dart files to version control
6. Default Locale: The fallback is always the English localization (_En variant)
7. Module Path: Ensure your Google Sheet name exactly matches your module folder path

Workflow Summary

1. Create l10n.yaml configuration in your module
2. Add your module path as a sheet name in the localization Google Sheets
3. Add localization keys and translations in the spreadsheet
4. Run melos run localization to download ARB files and generate Dart code
5. Add LocalizationModule mixin to your module class
6. Implement required methods (localizationsDelegate, onLocalizationUpdate, lookupLocalizations)
7. Export generated localization files
8. Register module in app's module list

Troubleshooting

Issue: ARB files not generated after running melos run localization

• Solution: Ensure your module folder path exactly matches the sheet name in Google Sheets

Issue: Generated Dart files not found

• Solution: Ensure flutter: generate: true is in pubspec.yaml and l10n.yaml exists in module root

Issue: Module localization returns null in widgets

• Solution: Make sure the module is registered in app's module list before MaterialApp

Issue: Localization not updating on language change

• Solution: The LocalizationModule mixin handles this automatically via onLocalizationUpdate

Issue: Manual ARB file changes not reflected

• Solution: Don't edit ARB files directly - update Google Sheets and run melos run localization