Localization

project_root/
└── lang/
    ├── en/
    │   ├── messages.json
    │   ├── validation.json
    │   ├── fields.json
    │   └── auth.json
    ├── fr/
    │   ├── messages.json
    │   ├── validation.json
    │   └── fields.json
    └── es/
        ├── messages.json
        └── validation.json

// Simple parameter replacement
String greeting = Lang.t('messages.greeting', parameters: {'name': 'Alice'});
// Result: "Hello Alice!"

// Multiple parameters
String welcome = Lang.t('messages.welcome', parameters: {
  'name': 'Alice',
  'app': 'MyApp'
});
// Result: "Welcome to MyApp"

// Field names in validation
String error = Lang.t('validation.required', parameters: {'field': 'email'});
// Result: "The email field is required"

// Dynamic values
String notification = Lang.t('notifications.order_placed', parameters: {
  'order_id': order.id,
  'total': order.total.toString(),
});
// Result: "Order #123 placed for $99.99"

// Basic pluralization
String item1 = Lang.choice('items.count', 1); // "1 item"
String item5 = Lang.choice('items.count', 5); // "5 items"

// With parameters
String apples1 = Lang.choice('apples', 1); // "You have 1 apple"
String apples3 = Lang.choice('apples', 3); // "You have 3 apples"

// Complex pluralization
String files = Lang.choice('files.uploaded', fileCount, parameters: {
  'count': fileCount,
  'user': userName,
});
// Result: "John uploaded 1 file" or "John uploaded 5 files"

// In templates
String message = Lang.t('cart.summary', parameters: {
  'item_count': itemCount,
  'total': totalPrice,
});
// Translation: "Your cart has :item_count item|Your cart has :item_count items"

// Set global locale for entire application
Lang.setGlobalLocale('en');
Lang.setFallbackLocale('en');

// Set locale for current request (per-request)
Lang.setRequestLocale('fr');

// Override locale for specific calls
String germanText = Lang.t('messages.hello', locale: 'de');

// Get current locale information
String currentLocale = Lang.getGlobalLocale();
String fallbackLocale = Lang.getFallbackLocale();

// List available locales
List<String> locales = Lang.getAvailableLocales();

// Middleware example for automatic locale detection
class LocaleMiddleware extends Middleware {
  @override
  Future<void> handle(Request request, Response response, Next next) async {
    // Detect locale from Accept-Language header
    String locale = _detectLocaleFromHeader(request.header('accept-language'));
    Lang.setRequestLocale(locale);

    await next();

    // Clean up request-specific locale
    // (This happens automatically when request ends)
  }
}

// Load package-specific translations
Lang.loadNamespace('auth', 'en', {
  'login': 'Sign In',
  'register': 'Create Account',
  'forgot_password': 'Forgot Password',
});

Lang.loadNamespace('auth', 'fr', {
  'login': 'Se Connecter',
  'register': 'Créer un Compte',
  'forgot_password': 'Mot de Passe Oublié',
});

// Use namespaced translations
String loginButton = Lang.t('login', namespace: 'auth');

// Mix global and namespaced translations
String pageTitle = Lang.t('auth.page_title', namespace: 'auth');
String welcomeMessage = Lang.t('messages.welcome'); // Global namespace

// Package structure example
class AuthPackage {
  static void initialize() {
    // Load translations for this package
    Lang.loadNamespace('auth', 'en', _englishTranslations);
    Lang.loadNamespace('auth', 'fr', _frenchTranslations);
  }

  static String loginTitle() => Lang.t('login.title', namespace: 'auth');
  static String loginButton() => Lang.t('login.button', namespace: 'auth');
}

// Translate field labels
String emailLabel = Lang.getField('email'); // Uses "fields.email" key
String passwordLabel = Lang.getField('password');
String firstNameLabel = Lang.getField('first_name');

// With namespace
String customField = Lang.getField('custom_field', namespace: 'my_package');

// In forms
class UserForm {
  Map<String, String> getFieldLabels() {
    return {
      'email': Lang.getField('email'),
      'password': Lang.getField('password'),
      'first_name': Lang.getField('first_name'),
      'last_name': Lang.getField('last_name'),
    };
  }
}

// Validation integration
class Validator {
  static String getErrorMessage(String field, String rule, [Map<String, dynamic>? params]) {
    String key = 'validation.${field}_$rule';
    if (!Lang.has(key)) {
      key = 'validation.$rule'; // Fallback to generic rule message
    }
    return Lang.t(key, parameters: {'field': Lang.getField(field), ...?params});
  }
}

// Add custom replacer for date formatting
Lang.addParameterReplacer((key, value, params) {
  if (key == 'date' && value is DateTime) {
    return _formatDate(value, params['locale'] ?? 'en');
  }
  return ':$key'; // Default replacement
});

// Add currency formatter
Lang.addParameterReplacer((key, value, params) {
  if (key == 'currency' && value is num) {
    return _formatCurrency(value, params['currency'] ?? 'USD');
  }
  return ':$key';
});

// Add number formatter
Lang.addParameterReplacer((key, value, params) {
  if (key == 'number' && value is num) {
    return _formatNumber(value, params['locale'] ?? 'en');
  }
  return ':$key';
});

// Usage with custom replacers
String invoice = Lang.t('invoice.due_date', parameters: {
  'date': DateTime.now().add(Duration(days: 30)),
  'amount': 99.99,
  'currency': 'EUR',
});
// Translation: "Invoice due on March 15, 2024 for €99.99"

// Complex object formatting
Lang.addParameterReplacer((key, value, params) {
  if (key == 'user' && value is User) {
    return value.fullName;
  }
  if (key == 'product' && value is Product) {
    return '${value.name} (${value.sku})';
  }
  return ':$key';
});

String orderMessage = Lang.t('order.shipped', parameters: {
  'user': currentUser,
  'product': orderedProduct,
  'tracking': trackingNumber,
});

// Set fallback locale
Lang.setFallbackLocale('en');

// Translation lookup order:
// 1. Try 'fr' locale with 'auth' namespace
// 2. Try 'fr' locale with global namespace
// 3. Try 'en' fallback locale with 'auth' namespace
// 4. Try 'en' fallback locale with global namespace
// 5. Return key itself if not found

String message = Lang.t('auth.login', locale: 'fr', namespace: 'auth');

// Handle missing translations gracefully
String safeTranslate(String key, {Map<String, dynamic>? parameters}) {
  if (Lang.has(key)) {
    return Lang.t(key, parameters: parameters);
  }

  // Log missing translation
  Khadem.logger.warning('Missing translation for key: $key');

  // Return a user-friendly fallback
  return _humanizeKey(key);
}

String _humanizeKey(String key) {
  return key.split('.').last.replaceAll('_', ' ').toUpperCase();
}

// Check translation existence
if (Lang.has('messages.greeting')) {
  return Lang.t('messages.greeting');
} else {
  return 'Hello!'; // Fallback
}

// Get raw translation value
String? rawTranslation = Lang.get('messages.greeting');
if (rawTranslation != null) {
  // Process raw translation
}