How to Translate a Flutter App with Azbox: Complete Guide

Translating your Flutter app is essential for reaching a global audience. Azbox provides a powerful Flutter SDK that simplifies the localization process by managing translations in the cloud and syncing them automatically to your app. This guide will walk you through the process of translating a Flutter app using the Azbox Flutter SDK.

Understanding Azbox Flutter SDK

The Azbox Flutter SDK provides a seamless way to manage translations for your Flutter app. It allows you to:

• Manage translations in the Azbox cloud platform
• Automatically sync translations to your app
• Support multiple languages without rebuilding
• Update translations over-the-air
• Collaborate with translators through the Azbox platform

Requirements

Before getting started, ensure you have:

• iOS: iOS 12+ or iPadOS 12+ device (iPhone, iPad) to test on. Xcode 14+ simulator works running iOS 16+
• iOS Development: Mac with Xcode 12+
• Android: Android 5.0+ device or emulator with “Google Play Store (Services)” installed
• Azbox Account: Paid Azbox plan (Starter or higher)
• Azbox Project: Configured Azbox project with your translations

Step 1: Install the Azbox Flutter SDK

Add the Azbox Flutter SDK to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  azbox-localization: ^1.0.0  # Use the latest version

Then run:

flutter pub get

To find the latest version, check the Azbox Flutter SDK documentation or the pub.dev package page.

Step 2: Get Your Azbox Credentials

Before configuring the SDK, you’ll need:

1. API Key: Found in your Azbox project settings
2. Project ID: Your Azbox project identifier

You can find these in your Azbox dashboard under Project Settings.

Step 3: Initialize Azbox in Your App

Initialize Azbox in your main.dart file before running your app:

lib/main.dart:

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize Azbox before running the app
  await Azbox.ensureInitialized(
    apiKey: 'Your API Key',
    projectId: 'Your project ID',
  );
  
  runApp(
    Azbox(
      child: MyApp(),
    ),
  );
}

Important Notes:

• Always call WidgetsFlutterBinding.ensureInitialized() before initializing Azbox
• The Azbox widget must wrap your root app widget
• Keep your API key secure and never commit it to version control

Step 4: Configure MaterialApp for Localization

Configure your MaterialApp to support localization using Azbox:

lib/main.dart:

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Use Azbox's localization delegates
      localizationsDelegates: context.localizationDelegates,
      
      // Use Azbox's supported locales
      supportedLocales: context.supportedLocales,
      
      // Use Azbox's current locale
      locale: context.locale,
      
      title: 'My Flutter App',
      home: MyHomePage(),
    );
  }
}

The Azbox SDK automatically provides:

• localizationDelegates: Handles translation loading
• supportedLocales: List of languages configured in your Azbox project
• locale: Current active locale

Step 5: Use Translations in Your App

Azbox provides multiple convenient ways to translate your texts:

Method 1: Using Text Widget Extension

The simplest way is to use the extension on Text widget:

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

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('welcome_title').translate(),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('welcome_message').translate(),
            SizedBox(height: 20),
            Text('button_submit').translate(),
          ],
        ),
      ),
    );
  }
}

Method 2: Using String Extension

You can also use the extension directly on strings:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final title = 'app_title'.translate();
    final description = 'app_description'.translate();
    
    return Column(
      children: [
        Text(title),
        Text(description),
      ],
    );
  }
}

Method 3: Using Static Function

Use the static translate function:

import 'package:azbox_localization/azbox_localization.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final title = translate('app_title');
    final subtitle = translate('app_subtitle');
    
    return Column(
      children: [
        Text(title),
        Text(subtitle),
      ],
    );
  }
}

Method 4: Using BuildContext Extension

Use the translate method on BuildContext:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text(context.translate('app_title')),
        Text(context.translate('app_subtitle')),
      ],
    );
  }
}

Step 6: Use Parameters in Translations

Azbox supports both positional and named arguments in translations.

Positional Arguments

Use positional arguments when you have ordered parameters:

In Azbox Dashboard:

// Translation key: "welcome_user"
// English: "Welcome, {0}! You have {1} messages."
// Spanish: "¡Bienvenido, {0}! Tienes {1} mensajes."

In Flutter:

Text('welcome_user').translate(
  args: ['John', '5'],
)
// English: "Welcome, John! You have 5 messages."
// Spanish: "¡Bienvenido, John! Tienes 5 mensajes."

Named Arguments

Use named arguments for better readability:

In Azbox Dashboard:

// Translation key: "user_greeting"
// English: "Hello, {name}! You are using {app}."
// Spanish: "¡Hola, {name}! Estás usando {app}."

In Flutter:

Text('user_greeting').translate(
  namedArgs: {
    'name': 'John',
    'app': 'Flutter',
  },
)
// English: "Hello, John! You are using Flutter."
// Spanish: "¡Hola, John! Estás usando Flutter."

Step 7: Handle Pluralization

Azbox supports pluralization using ICU message format:

In Azbox Dashboard:

// Translation key: "items_count"
// English: "{count, plural, =0{No items} one{1 item} other{{count} items}}"
// Spanish: "{count, plural, =0{No hay elementos} one{1 elemento} other{{count} elementos}}"

In Flutter:

class ItemCountWidget extends StatelessWidget {
  final int count;
  
  ItemCountWidget({required this.count});
  
  @override
  Widget build(BuildContext context) {
    return Text('items_count').translate(
      namedArgs: {'count': count.toString()},
    );
  }
}

// Usage:
// ItemCountWidget(count: 0) → "No items" (English) / "No hay elementos" (Spanish)
// ItemCountWidget(count: 1) → "1 item" (English) / "1 elemento" (Spanish)
// ItemCountWidget(count: 5) → "5 items" (English) / "5 elementos" (Spanish)

Step 8: Change Language Programmatically

Allow users to switch languages:

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

class LanguageSwitcher extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return DropdownButton<String>(
      value: context.locale.languageCode,
      items: [
        DropdownMenuItem(value: 'en', child: Text('English')),
        DropdownMenuItem(value: 'es', child: Text('Español')),
        DropdownMenuItem(value: 'fr', child: Text('Français')),
      ],
      onChanged: (String? newLocale) {
        if (newLocale != null) {
          Azbox.setLocale(Locale(newLocale));
        }
      },
    );
  }
}

Step 9: Handle Loading States

Show loading indicators while translations are being fetched:

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: context.localizationDelegates,
      supportedLocales: context.supportedLocales,
      locale: context.locale,
      builder: (context, child) {
        // Show loading while translations are loading
        if (!Azbox.isInitialized) {
          return MaterialApp(
            home: Scaffold(
              body: Center(child: CircularProgressIndicator()),
            ),
          );
        }
        return child!;
      },
      home: MyHomePage(),
    );
  }
}

Step 10: Configure Translation Keys in Azbox

Before using translations, set them up in your Azbox dashboard:

1. Log in to Azbox Dashboard
2. Navigate to your project
3. Go to Translations section
4. Add translation keys for each text you want to translate
5. Add translations for each language you support

Example Translation Keys:

• app_title: “My Flutter App” (English), “Mi Aplicación Flutter” (Spanish)
• welcome_message: “Welcome to our app!” (English), “¡Bienvenido a nuestra aplicación!” (Spanish)
• button_submit: “Submit” (English), “Enviar” (Spanish)

Best Practices

1. Use Descriptive Translation Keys

Bad:

Key: "msg1"
Value: "Submit"

Good:

Key: "button_submit"
Value: "Submit"

2. Organize Keys by Feature

Group related translations:

auth_login
auth_logout
auth_signup

dashboard_title
dashboard_welcome

settings_language
settings_theme

3. Provide Context in Key Names

Use descriptive names that indicate context:

button_delete_item
button_delete_account
action_delete_comment

4. Handle Missing Translations

Azbox provides fallback to the default language. Always ensure your default language (usually English) has all translations:

// If translation is missing, Azbox falls back to default language
Text('some_key').translate() // Falls back to English if translation missing

5. Test All Languages

Test your app in all supported languages to ensure:

• All translations are present
• UI layout accommodates longer text
• RTL languages display correctly (if supported)

6. Keep API Key Secure

Never commit your API key to version control:

Use environment variables:

import 'package:flutter_dotenv/flutter_dotenv.dart';

void main() async {
  await dotenv.load(fileName: ".env");
  
  await Azbox.ensureInitialized(
    apiKey: dotenv.env['AZBOX_API_KEY']!,
    projectId: dotenv.env['AZBOX_PROJECT_ID']!,
  );
  
  runApp(Azbox(child: MyApp()));
}

Create .env file (add to .gitignore):

AZBOX_API_KEY=your_api_key_here
AZBOX_PROJECT_ID=your_project_id_here

Common Pitfalls

1. Forgetting to Initialize Azbox

Always initialize Azbox before running your app:

// ❌ Won't work
void main() {
  runApp(MyApp());
}

// ✅ Correct
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Azbox.ensureInitialized(apiKey: '...', projectId: '...');
  runApp(Azbox(child: MyApp()));
}

2. Not Wrapping App with Azbox Widget

The Azbox widget must wrap your root app:

// ❌ Won't work
runApp(MyApp());

// ✅ Correct
runApp(Azbox(child: MyApp()));

3. Not Configuring MaterialApp

Make sure to use Azbox’s localization delegates:

// ❌ Won't work
MaterialApp(
  home: MyHomePage(),
)

// ✅ Correct
MaterialApp(
  localizationsDelegates: context.localizationDelegates,
  supportedLocales: context.supportedLocales,
  locale: context.locale,
  home: MyHomePage(),
)

4. Hardcoding Strings

Bad:

Text('Welcome')

Good:

Text('welcome_message').translate()

Advanced: Custom Locale Detection

Detect and set locale based on device settings:

import 'package:flutter/material.dart';
import 'package:azbox_localization/azbox_localization.dart';
import 'dart:ui' as ui;

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Get device locale
  final deviceLocale = ui.PlatformDispatcher.instance.locale;
  
  await Azbox.ensureInitialized(
    apiKey: 'Your API Key',
    projectId: 'Your project ID',
  );
  
  // Set locale based on device
  final supportedLocales = ['en', 'es', 'fr'];
  final locale = supportedLocales.contains(deviceLocale.languageCode)
      ? deviceLocale
      : Locale('en');
  
  Azbox.setLocale(locale);
  
  runApp(Azbox(child: MyApp()));
}

Advanced: Persist Language Preference

Save user’s language choice:

import 'package:shared_preferences/shared_preferences.dart';

class LanguageService {
  static const String _languageKey = 'selected_language';
  
  static Future<void> saveLanguage(String languageCode) async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString(_languageKey, languageCode);
    Azbox.setLocale(Locale(languageCode));
  }
  
  static Future<Locale?> getSavedLanguage() async {
    final prefs = await SharedPreferences.getInstance();
    final languageCode = prefs.getString(_languageKey);
    return languageCode != null ? Locale(languageCode) : null;
  }
}

// Usage in app initialization
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Azbox.ensureInitialized(
    apiKey: 'Your API Key',
    projectId: 'Your project ID',
  );
  
  // Load saved language
  final savedLocale = await LanguageService.getSavedLanguage();
  if (savedLocale != null) {
    Azbox.setLocale(savedLocale);
  }
  
  runApp(Azbox(child: MyApp()));
}

Advanced: Handle Translation Updates

Azbox can update translations over-the-air. Handle update events:

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    
    // Listen for translation updates
    Azbox.onTranslationsUpdated = () {
      setState(() {
        // Rebuild UI with new translations
      });
    };
  }
  
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: context.localizationDelegates,
      supportedLocales: context.supportedLocales,
      locale: context.locale,
      home: MyHomePage(),
    );
  }
}

Advanced: Error Handling

Handle errors during initialization:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  try {
    await Azbox.ensureInitialized(
      apiKey: 'Your API Key',
      projectId: 'Your project ID',
    );
    
    runApp(Azbox(child: MyApp()));
  } catch (e) {
    // Handle initialization error
    print('Azbox initialization failed: $e');
    
    // Fallback: Run app without Azbox (use hardcoded translations)
    runApp(MyApp());
  }
}

Testing Your Implementation

Test on iOS

1. Open your project in Xcode
2. Select a simulator (iOS 16+)
3. Run the app
4. Test language switching

Test on Android

1. Use an Android 5.0+ device or emulator
2. Ensure Google Play Services is installed
3. Run the app
4. Test language switching

Test Translation Updates

1. Update a translation in Azbox dashboard
2. The app should automatically fetch and display the updated translation
3. No app rebuild required!

Conclusion

Localizing your Flutter app with Azbox is straightforward when you follow these steps:

1. Install the azbox-localization package
2. Get your API key and Project ID from Azbox dashboard
3. Initialize Azbox in your main.dart before running the app
4. Wrap your app with the Azbox widget
5. Configure MaterialApp with Azbox’s localization delegates
6. Use translations throughout your app with the convenient extension methods
7. Handle parameters and pluralization as needed
8. Test thoroughly in all supported languages

By using Azbox, you benefit from:

• Cloud-based translation management - Update translations without app updates
• Collaborative workflow - Work with translators through the Azbox platform
• Automatic syncing - Translations sync automatically to your app
• Over-the-air updates - Update translations without rebuilding your app

Get Started with Azbox

Ready to streamline your Flutter localization workflow?

1. Sign up for Azbox - Get a Starter plan or higher
2. Create a project - Set up your Flutter project in Azbox
3. Add translations - Import or add your translation keys
4. Install the SDK - Follow this guide to integrate Azbox
5. Start localizing - Use Azbox’s powerful features to manage translations

Explore AZbox’s localization platform and streamline your translation workflow:

View AZbox Plans and Pricing

Read the Flutter SDK Documentation