Flutter Locale Master

A comprehensive, production-ready Flutter localization package with automatic text direction switching, custom widgets, and developer-friendly APIs. Built for modern Flutter apps with performance and ease of use in mind.

✨ Features

🚀 One-line initialization with asset-based translations
📱 Built-in pluralization with ICU MessageFormat syntax
🔧 Parameter interpolation with named placeholders
🎨 Context extensions for convenient access
🧵 String extensions for BuildContext-free usage
🏗️ Custom widgets for automatic translation
📦 Type-safe API with full null-safety
🎯 Performance optimized with caching and preloading
📚 Rich documentation and examples

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  flutter_locale_master: ^1.0.4

🚀 Quick Start

1. Setup Translation Files

Create translation files in your assets/ directory:

assets/
  lang/
    en/
      en.json          # General translations (default namespace)
      fields.json      # Form field labels
      validation.json  # Validation messages
    ar/
      ar.json          # General translations (default namespace)
      fields.json      # Form field labels
      validation.json  # Validation messages
    fr/
      fr.json          # General translations (default namespace)
      fields.json      # Form field labels
      validation.json  # Validation messages

Example en.json (general translations):

{
  "hello": "Hello",
  "welcome": "Welcome :name!",
  "item_count": "no items | :count item | :count items",
  "current_time": "Current time: :time",
  "user_greeting": "Hello :name, welcome back!"
}

Example fields.json (form field labels):

{
  "email": "Email Address",
  "password": "Password",
  "first_name": "First Name",
  "last_name": "Last Name"
}

Example validation.json (validation messages):

{
  "required": "This field is required",
  "email_invalid": "Please enter a valid email address",
  "password_too_short": "Password must be at least 8 characters",
  "passwords_not_match": "Passwords do not match",
  "phone_invalid": "Please enter a valid phone number",
  "min_length": "Minimum length is :min characters",
  "max_length": "Maximum length is :max characters"
}


### 2. Initialize the Package

```dart
import 'package:flutter/material.dart';
import 'package:flutter_locale_master/flutter_locale_master.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize with asset translations
  final localeMaster = await FlutterLocaleMaster.initialize(
    basePath: 'lang/',
    initialLocale: const Locale('en'),
    fallbackLocale: const Locale('en'),
  );

  runApp(MyApp(localeMaster: localeMaster));
}

3. Wrap Your App

class MyApp extends StatelessWidget {
  final FlutterLocaleMaster localeMaster;

  const MyApp({super.key, required this.localeMaster});

  @override
  Widget build(BuildContext context) {
    return localeMaster.wrapApp(
      (locale) => MaterialApp(
        title: 'My App',
        localizationsDelegates: [
          localeMaster.delegate,
          GlobalMaterialLocalizations.delegate,
          GlobalWidgetsLocalizations.delegate,
          GlobalCupertinoLocalizations.delegate,
        ],
        supportedLocales: localeMaster.supportedLocales,
        locale: locale,
        home: const HomePage(),
      ),
    );
  }
}

That's it! Your app now supports multiple languages with automatic RTL/LTR switching.

🎯 Usage Examples

Basic Translation

Using Widgets (Recommended)

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: TranslatedText('app_title'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            TranslatedText(
              'welcome',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
            const SizedBox(height: 20),
            TranslatedText(
              'current_time',
              parameters: {'time': DateTime.now().toString()},
            ),
          ],
        ),
      ),
    );
  }
}

Using Context Extensions

class ProfilePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text(context.tr('profile_title')),
        Text(context.tr('welcome', parameters: {'name': user.name})),
        Text(context.plural('item_count', itemCount)),
        Text(context.field('email')),
      ],
    );
  }
}

Using String Extensions

class Utils {
  static String getGreeting(String userName) {
    return 'welcome'.tr(parameters: {'name': userName});
  }

  static String formatItemCount(int count) {
    return 'item_count'.plural(count);
  }

  static bool hasTranslation(String key) {
    return key.exists();
  }
}

class FormLabels {
  static String get email => 'email'.field();
  static String get password => 'password'.field();
}

Advanced Features

Locale Management

class LanguageSelector extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return DropdownButton<Locale>(
      value: context.currentLocaleObj,
      items: context.supportedLocales.map((localeString) {
        final locale = Locale(localeString);
        return DropdownMenuItem(
          value: locale,
          child: Text(locale.languageCode.toUpperCase()),
        );
      }).toList(),
      onChanged: (newLocale) {
        if (newLocale != null) {
          context.setLocaleObj(newLocale);
        }
      },
    );
  }
}

Rich Text Translation

TranslatedRichText.rich(
  'terms_agreement',
  parameters: {'app': 'MyApp'},
  spanBuilder: (translatedText) {
    final parts = translatedText.split(':app');
    return TextSpan(
      children: [
        TextSpan(text: parts[0]),
        TextSpan(
          text: 'MyApp',
          style: TextStyle(fontWeight: FontWeight.bold),
        ),
        if (parts.length > 1) TextSpan(text: parts[1]),
      ],
    );
  },
)

Locale Consumer for Complex UI

class AdaptiveLayout extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return LocaleConsumer(
      builder: (context, localization, child) {
        final isRTL = localization.notifier.isRTL;
        return Directionality(
          textDirection: isRTL ? TextDirection.rtl : TextDirection.ltr,
          child: Row(
            children: [
              if (!isRTL) child!,
              Expanded(
                child: Text(localization.provider.t('content')),
              ),
              if (isRTL) child!,
            ],
          ),
        );
      },
      child: IconButton(
        icon: Icon(Icons.menu),
        onPressed: () => Scaffold.of(context).openDrawer(),
      ),
    );
  }
}

🔧 API Reference