NativeLan Flutter SDK

The NativeLan Flutter SDK allows you to deliver real-time over-the-air (OTA) localization string updates directly to your Flutter applications. By integrating seamlessly with Flutter's localization framework, your widgets instantly resolve to the latest published translation assets.

💻 Installation

Add Dependency

Add the SDK dependency to your project's pubspec.yaml:

dependencies:
  nativelan: ^0.0.1

Or reference the git repository directly:

dependencies:
  nativelan:
    git:
      url: https://github.com/Work-On-Idea/nativelan-flutter.git

🚀 Usage Guide

1. Wrap Root App with NativeLanScope

Wrap your main application root widget inside NativeLanScope to listen for real-time background translation updates:

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

void main() {
  runApp(
    const NativeLanScope(
      child: MyApp(),
    ),
  );
}

2. Configure MaterialApp Localizations

Register NativeLanLocalizationsDelegate inside your MaterialApp localizations hook:

import 'package:flutter_localizations/flutter_localizations.dart';

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      // Configure NativeLan delegates
      localizationsDelegates: [
        NativeLanLocalizationsDelegate(
          config: NativeLanConfig(
            projectId: 'your_project_id',
            sdkKey: 'nl_sk_live_...',
            baseUrl: 'https://your-nativelan-server.com',
            prerelease: false, // Set to true inside Dev/QA builds
            appVersion: '1.0.0', // Enables bundle version freeze rules
          ),
        ),
        // Fallbacks for Flutter framework widgets
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: const [
        Locale('en', 'US'),
        Locale('ar', 'IQ'),
      ],
      home: const HomeScreen(),
    );
  }
}

3. Retrieve Strings Automatically

Any widget within the subtree can now retrieve dynamic translations. If the OTA bundles are not yet synced or the device is offline, standard calls instantly fall back to local translation keys or cached values:

// Retrieve standard translations:
final welcomeMsg = NativeLanLocalizations.of(context)?.translate('welcome_message') ?? 'Welcome';

// Supporting token replacements (%s placeholder formatting):
final formatted = NativeLanLocalizations.of(context)?.translate('user_score', ['John', 42]) ?? 'Hello, John';

4. Manual String Retrieval (Optional)

If you need to retrieve a translation without relying on a BuildContext (e.g., inside business logic, controllers, or services):

final directVal = NativeLanClient(config).t("welcome_message");

Libraries

nativelan