Localization by Muz

A simple Flutter package for easy JSON-based localization. No extra commands, no code generation - just add the package and start localizing!

Features

• JSON-based Localization: Use a simple JSON file for organized translations
• Parameter Interpolation: Support for dynamic text with placeholders like {name} via args map
• Number/Date Formatting: Built-in helpers for formatting numbers, currencies, percentages, dates, and times with locale support
• Namespaces/Dotted Keys: Support for nested JSON structures and dotted key notation (e.g., user.profile.name)
• Instant Language Switching: Change languages instantly without app restart
• No Code Generation: No need for build runner or code generation commands
• Simple Setup: Just add the package and start using

Getting Started

Add the package to your pubspec.yaml:

dependencies:
  localization_by_muz: ^2.1.0

Usage

JSON-based Localization

1. Create a localization.json file in your lib/ directory (required path for this package):

{
  "helloWorld": {
    "en": "Hello World",
    "fr": "Bonjour Le Monde",
    "es": "Hola Mundo"
  },
  "welcome": {
    "en": "Welcome", 
    "fr": "Bienvenue",
    "es": "Bienvenido"
  },
  "goodbye": {
    "en": "Goodbye",
    "fr": "Au revoir", 
    "es": "Adiós"
  }
}

2. Add it to your app's pubspec.yaml assets so Flutter bundles it:

flutter:
  assets:
    - lib/localization.json

Note: The package reads from lib/localization.json via rootBundle. Keep this exact path and add it to assets as shown above.

3. Use in your Flutter app:

import 'package:flutter/material.dart';
import 'package:localization_by_muz/localization_by_muz.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return LocalizationProvider(
      defaultLocale: 'en',
      child: LocalizedBuilder(
        builder: (context, locale) {
          return MaterialApp(
            title: "appTitle".localize(),
            home: MyHomePage(),
          );
        },
      ),
    );
  }
}

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("helloWorld".localize()),
      ),
      body: Column(
        children: [
          Text("welcome".localize()),
          Text("goodbye".localize()),
          ElevatedButton(
            onPressed: () => LocalizationProvider.setLocale(context, 'fr'),
            child: Text("Switch to French"),
          ),
          ElevatedButton(
            onPressed: () => LocalizationProvider.setLocale(context, 'es'),
            child: Text("Switch to Spanish"),
          ),
        ],
      ),
    );
  }
}

That's it! Just wrap your MaterialApp with LocalizedBuilder once, and you're done. The package automatically:

• Initializes the localization system in the background
• Handles persistent locale storage
• Rebuilds all localized text when language changes
• Provides instant language switching without app restart
• No need to wrap individual screens with LocalizedBuilder

Language Switching

To change the language instantly:

LocalizationProvider.setLocale(context, 'fr'); // Switch to French
LocalizationProvider.setLocale(context, 'en'); // Switch to English
LocalizationProvider.setLocale(context, 'es'); // Switch to Spanish

The UI will update instantly without requiring app restart or refresh!

Parameter Interpolation

Support for dynamic text with placeholders using JSON-based translations:

// In localization.json:
// {
//   "userWelcome": {
//     "en": "Welcome back, {username}!",
//     "fr": "Bon retour, {username}!",
//     "es": "¡Bienvenido de vuelta, {username}!"
//   },
//   "greeting": {
//     "en": "Hello {name}, welcome to {app}!",
//     "fr": "Bonjour {name}, bienvenue dans {app}!",
//     "es": "¡Hola {name}, bienvenido a {app}!"
//   }
// }

// Use localizeArgs for translations with parameters
Text("userWelcome".localizeArgs(
  args: {"username": "Alice"}
))

Text("greeting".localizeArgs(
  args: {
    "name": "John",
    "app": "My App"
  }
))

Number and Date Formatting

The package includes built-in formatting helpers for numbers, currencies, percentages, dates, and times with locale-aware formatting:

import 'package:localization_by_muz/localization_by_muz.dart';

// Number formatting
String formattedNumber = FormattingHelpers.formatNumber(1234.56, 'en'); // "1,234.56"
String germanNumber = FormattingHelpers.formatNumber(1234.56, 'de'); // "1.234,56"
String frenchNumber = FormattingHelpers.formatNumber(1234.56, 'fr'); // "1 234,56"

// Currency formatting
String usdAmount = FormattingHelpers.formatCurrency(1234.56, 'en', 'USD'); // "$1,234.56"
String euroAmount = FormattingHelpers.formatCurrency(1234.56, 'de', 'EUR'); // "1.234,56 €"

// Percentage formatting
String percentage = FormattingHelpers.formatPercentage(0.1234, 'en'); // "12.3%"
String germanPercent = FormattingHelpers.formatPercentage(0.1234, 'de'); // "12,3 %"

// Date formatting
String usDate = FormattingHelpers.formatDate(DateTime.now(), 'en'); // "12/25/2023"
String germanDate = FormattingHelpers.formatDate(DateTime.now(), 'de'); // "25.12.2023"
String customDate = FormattingHelpers.formatDate(DateTime.now(), 'en', pattern: 'yyyy-MM-dd'); // "2023-12-25"

// Time formatting
String usTime = FormattingHelpers.formatTime(DateTime.now(), 'en'); // "3:30 PM"
String germanTime = FormattingHelpers.formatTime(DateTime.now(), 'de'); // "15:30"

Optional Intl Integration: The formatting helpers are designed with a feature flag (kUseIntlFormatting) that can be enabled to use the intl package for more advanced formatting when needed.

Namespaces and Dotted Keys

Support for nested JSON structures and dotted key notation for better organization:

{
  "user": {
    "profile": {
      "name": {
        "en": "Name",
        "fr": "Nom",
        "es": "Nombre"
      },
      "email": {
        "en": "Email Address",
        "fr": "Adresse e-mail",
        "es": "Dirección de correo"
      }
    },
    "settings": {
      "theme": {
        "en": "Theme",
        "fr": "Thème",
        "es": "Tema"
      }
    }
  },
  "app": {
    "title": {
      "en": "My Application",
      "fr": "Mon Application",
      "es": "Mi Aplicación"
    }
  }
}

Use dotted notation to access nested translations:

// Access nested translations using dotted keys
Text("user.profile.name".localize()), // "Name" (in English)
Text("user.profile.email".localize()), // "Email Address"
Text("user.settings.theme".localize()), // "Theme"
Text("app.title".localize()), // "My Application"

// Also works with parameter interpolation
Text("user.welcome.message".localizeArgs(
  args: {"username": "John"}
)), // If the nested key contains "Welcome back, {username}!"

Backward Compatibility: The package still supports flat key structures, so existing implementations continue to work without changes.

Migration from Older Versions

If you're upgrading from an older version where you had to wrap each screen with LocalizedBuilder:

Old approach (no longer needed on each screen):

class MyScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return LocalizedBuilder(  // ❌ Remove from individual screens
      builder: (context, locale) {
        return Scaffold(
          appBar: AppBar(title: Text("title".localize())),
          body: Text("content".localize()),
        );
      },
    );
  }
}

New approach - wrap MaterialApp once:

// In your main app file
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return LocalizationProvider(
      defaultLocale: 'en',
      child: LocalizedBuilder(  // ✅ Wrap MaterialApp once
        builder: (context, locale) {
          return MaterialApp(
            title: 'appTitle'.localize(),
            home: MyScreen(),
          );
        },
      ),
    );
  }
}

// Individual screens - no wrapper needed
class MyScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(  // ✅ Direct usage - automatic rebuilding
      appBar: AppBar(title: Text("title".localize())),
      body: Text("content".localize()),
    );
  }
}

Key changes:

1. Remove LocalizedBuilder from individual screens
2. Wrap your MaterialApp with LocalizedBuilder once in your main app widget
3. All screens will automatically rebuild when language changes!

Complete Working Example

Here's a complete example showing language selection and switching:

import 'package:flutter/material.dart';
import 'package:localization_by_muz/localization_by_muz.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return LocalizationProvider(
      defaultLocale: 'en',
      child: LocalizedBuilder(
        builder: (context, locale) {
          return MaterialApp(
            title: 'appTitle'.localize(),
            home: LanguageSelectionScreen(),
          );
        },
      ),
    );
  }
}

class LanguageSelectionScreen extends StatelessWidget {
  final List<Map<String, String>> languages = [
    {'code': 'en', 'name': 'English'},
    {'code': 'fr', 'name': 'French'},
    {'code': 'es', 'name': 'Spanish'},
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('selectLanguage'.localize()),
      ),
      body: ListView.builder(
        itemCount: languages.length,
        itemBuilder: (context, index) {
          final language = languages[index];
          return ListTile(
            title: Text(language['name']!),
            onTap: () {
              LocalizationProvider.setLocale(context, language['code']!);
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(
                  content: Text(
                    'languageChangedTo'.localizeArgs(
                      args: {'language': language['name']!}
                    )
                  ),
                ),
              );
            },
          );
        },
      ),
    );
  }
}

With corresponding localization.json:

{
  "appTitle": {
    "en": "Localization Demo",
    "fr": "Démo de Localisation", 
    "es": "Demo de Localización"
  },
  "helloWorld": {
    "en": "Hello World",
    "fr": "Bonjour Le Monde",
    "es": "Hola Mundo"
  },
  "welcome": {
    "en": "Welcome to our app!",
    "fr": "Bienvenue dans notre application!",
    "es": "¡Bienvenido a nuestra aplicación!"
  },
  "goodbye": {
    "en": "Goodbye! See you later",
    "fr": "Au revoir! À bientôt", 
    "es": "¡Adiós! Hasta luego"
  },
  "selectLanguage": {
    "en": "Select Language",
    "fr": "Sélectionner la langue",
    "es": "Seleccionar idioma"
  },
  "languageChangedTo": {
    "en": "Language changed to {language}",
    "fr": "Langue changée en {language}",
    "es": "Idioma cambiado a {language}"
  }
}

Features Breakdown

• JSON-based localization: Simple JSON file approach for organized translations
• Parameter interpolation: Dynamic text with {placeholder} support via .localizeArgs(args: {...})
• Number/date formatting: Built-in locale-aware formatting for numbers, currencies, percentages, dates, and times
• Namespaces/dotted keys: Support for nested JSON structures and dotted key notation for better organization
• Missing key diagnostics: Track missing translation keys for debugging
• Instant updates: Language changes reflect immediately in the UI without app restart or manual rebuilding
• Zero configuration: No build runner or code generation required
• Simple API: Just use .localize() for simple text and .localizeArgs() for parameterized text
• Automatic rebuilding: Wrap MaterialApp once with LocalizedBuilder - all screens update automatically
• Fallback support: If translation not found, returns the key as fallback text
• Provider pattern: Efficient state management using Flutter's provider pattern
• Easy initialization: Automatic initialization - just wrap your app with LocalizationProvider

Additional Information

This package is designed to make Flutter localization as simple as possible using JSON-based translations. Perfect for projects of any size that need organized, maintainable localization.

For issues and feature requests, please visit our GitHub repository.

Author

Muzamil Ghafoor

• GitHub: @muzzammil763

---

Made By Muzamil Ghafoor With ❤️ For The Flutter Developers To Make Localization Easy