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:
API Key: Found in your Azbox project settings
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:
Log in to Azbox Dashboard
Navigate to your project
Go to Translations section
Add translation keys for each text you want to translate
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
Open your project in Xcode
Select a simulator (iOS 16+)
Run the app
Test language switching
Test on Android
Use an Android 5.0+ device or emulator
Ensure Google Play Services is installed
Run the app
Test language switching
Test Translation Updates
Update a translation in Azbox dashboard
The app should automatically fetch and display the updated translation
No app rebuild required!
Conclusion
Localizing your Flutter app with Azbox is straightforward when you follow these steps:
Install the azbox-localization package
Get your API key and Project ID from Azbox dashboard
Initialize Azbox in your main.dart before running the app
Wrap your app with the Azbox widget
Configure MaterialApp with Azbox’s localization delegates
Use translations throughout your app with the convenient extension methods
Handle parameters and pluralization as needed
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?
Sign up for Azbox - Get a Starter plan or higher
Create a project - Set up your Flutter project in Azbox
Add translations - Import or add your translation keys
Install the SDK - Follow this guide to integrate Azbox
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