Modular Flutter Localization

Organize your Flutter translations by feature/module for better scalability and reusability.

✨ Features

🚀 Quick Start

1. Install the Extension

Install from the VS Code Marketplace or search for "Modular Flutter Localization" in VS Code.

2. Create Your First Module

Create ARB files in your feature folder:

lib/features/auth/l10n/
├── auth_en.arb
└── auth_ar.arb

auth_en.arb:

{
  "@@locale": "en",
  "@@context": "auth",
  "email": "Email",
  "password": "Password",
  "login": "Login",
  "welcomeBack": "Welcome back, {name}!"
}

auth_ar.arb:

{
  "@@locale": "ar",
  "@@context": "auth",
  "email": "البريد الإلكتروني",
  "password": "كلمة المرور",
  "login": "تسجيل الدخول",
  "welcomeBack": "مرحباً بعودتك، {name}!"
}

3. Generate Code

The extension will auto-generate on save (if watch mode is enabled), or use the command palette:

• Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
• Type "Modular L10n: Generate Translations"
• Press Enter

4. Use in Your App

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'generated/l10n/l10n.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      locale: const Locale('en'),
      supportedLocales: S.supportedLocales,
      localizationsDelegates: const [
        S.delegate,
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      home: const LoginScreen(),
    );
  }
}

class LoginScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          // Access translations with type-safe nested syntax
          TextField(decoration: InputDecoration(labelText: S.auth.email)),
          TextField(decoration: InputDecoration(labelText: S.auth.password)),
          ElevatedButton(
            onPressed: () {},
            child: Text(S.auth.login),
          ),
          // With parameters
          Text(S.auth.welcomeBack('Ahmed')),
        ],
      ),
    );
  }
}

📁 Project Structure

your_flutter_app/
├── lib/
│   ├── features/
│   │   ├── auth/
│   │   │   ├── l10n/
│   │   │   │   ├── auth_en.arb    ← English translations
│   │   │   │   └── auth_ar.arb    ← Arabic translations
│   │   │   ├── screens/
│   │   │   └── widgets/
│   │   ├── home/
│   │   │   ├── l10n/
│   │   │   │   ├── home_en.arb
│   │   │   │   └── home_ar.arb
│   │   │   └── ...
│   │   └── settings/
│   │       ├── l10n/
│   │       │   ├── settings_en.arb
│   │       │   └── settings_ar.arb
│   │       └── ...
│   └── generated/
│       └── l10n/                  ← Generated code (don't edit)
│           ├── s.dart
│           ├── auth_l10n.dart
│           ├── home_l10n.dart
│           └── settings_l10n.dart

⚙️ Configuration

Add to your .vscode/settings.json:

{
  "modularL10n.outputPath": "lib/generated/l10n",
  "modularL10n.supportedLocales": ["en", "ar"],
  "modularL10n.defaultLocale": "en",
  "modularL10n.arbFilePattern": "**/l10n/*.arb",
  "modularL10n.watchMode": true,
  "modularL10n.generateCombinedArb": true,
  "modularL10n.className": "S"
}

🛠️ Commands

📖 ARB File Format

Basic String

{
  "greeting": "Hello"
}

With Description

{
  "greeting": "Hello",
  "@greeting": {
    "description": "Simple greeting shown on home screen"
  }
}

With Placeholders

{
  "welcomeMessage": "Welcome, {name}!",
  "@welcomeMessage": {
    "description": "Welcome message with user name",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "John"
      }
    }
  }
}

With Pluralization

{
  "itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
  "@itemCount": {
    "description": "Number of items in cart",
    "placeholders": {
      "count": {
        "type": "int"
      }
    }
  }
}

Usage:

Text(S.home.itemCount(0))   // "No items"
Text(S.home.itemCount(1))   // "1 item"
Text(S.home.itemCount(5))   // "5 items"

🔄 Reusing Modules

One of the main benefits of this modular approach is easy module reuse:

# Copy auth feature to new project with all translations
cp -r old_project/lib/features/auth new_project/lib/features/

# Run generate in new project - translations are ready!

🌐 RTL Support

For full RTL support, use the companion Dart package:

import 'package:modular_l10n/modular_l10n.dart';

// Check if locale is RTL
if (LocaleUtils.isRtl(locale)) {
  // Handle RTL layout
}

// Get text direction
TextDirection direction = LocaleUtils.getTextDirection(locale);

// Use extension
bool isRtl = locale.isRtl;

📦 Companion Package

For runtime utilities like LocaleProvider and RTL support, install the modular_l10n Dart package:

dependencies:
  modular_l10n: ^1.0.0

📋 Naming Conventions

🔀 Migration from flutter_intl

If you're migrating from flutter_intl:

1. Create l10n folders in your feature directories
2. Split your single .arb file into module-specific files
3. Remove the flutter_intl configuration from pubspec.yaml
4. Run "Modular L10n: Generate Translations"

❓ FAQ

🐛 Issues & Contributions

Found a bug or have a feature request?

• Report an issue
• Contribute on GitHub

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by Utanium